home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / mc220.zip / LIBRARY.DOC < prev    next >
Text File  |  1992-02-24  |  173KB  |  6,134 lines

  1.           
  2.           
  3.           
  4.           
  5.           
  6.           
  7.           
  8.           
  9.           
  10.           
  11.           
  12.           
  13.           ===========================================================
  14.           MM   MM  IIIIIII    CCCC   RRRRRR     OOO             CCCC
  15.           M M M M     I      C    C  R     R   O   O           C    C
  16.           M  M  M     I     C        R     R  O     O         C
  17.           M     M     I     C        RRRRRR   O     O  -----  C
  18.           M     M     I     C        R   R    O     O         C
  19.           M     M     I      C    C  R    R    O   O           C    C
  20.           M     M  IIIIIII    CCCC   R     R    OOO             CCCC
  21.           ===========================================================
  22.     
  23.     
  24.     
  25.     
  26.     
  27.                              A compact 'C' compiler
  28.                                for small systems.
  29.     
  30.     
  31.                                Library Reference
  32.     
  33.     
  34.     
  35.     
  36.     
  37.                                   Release 2.2
  38.     
  39.                                Revised 24-Jan-92
  40.     
  41.     
  42.     
  43.     
  44.     
  45.     
  46.     
  47.     
  48.     
  49.     
  50.     
  51.     
  52.     
  53.     
  54.     
  55.                        Copyright 1988,1992 Dave Dunfield
  56.                               All rights reserved
  57.     MICRO-C Library                                                  Page: 1
  58.  
  59.  
  60.     1. THE MICRO-C LIBRARIES
  61.     
  62.           The MICRO-C distribution disk includes the 'C'  and  'ASM'  source
  63.        code for a very complete function library which is configured for use
  64.        on an IBM/PC under the MS-DOS operating system. These routines may be
  65.        also be used as "example" programs, providing  insight  into  MICRO-C
  66.        programming techniques.
  67.     
  68.           All functions except for the lowest level I/O routines  are  coded
  69.        in 'C', and should compile on any MICRO-C system. Note that some  low
  70.        level functions in the library are written in 'C' using  still  lower
  71.        level routines. Although this makes the library highly  portable  and
  72.        reduces the number of routines you have to re-write  for  a  specific
  73.        system, the resultant function will be less efficent than  one  which
  74.        directly uses the operating system services.
  75.     
  76.           If you are implementing MICRO-C an a small system  and  intend  to
  77.        use it for serious programming, I strongly recommend that you re-code
  78.        all of the low level library functions in assembly language.
  79.     
  80.           Note that since library routines are often  used  in  applications
  81.        where code size and execution speed are of primary importance, it may
  82.        be desirable to recode some or all of the other library  routines  in
  83.        assembly language as well.
  84.     
  85.           For those who intend to make only casual use of  MICRO-C,  or  who
  86.        wish to experiment with it simply for the  learning  experience,  the
  87.        'C' versions of the low level library functions should be  more  than
  88.        sufficient.
  89.     
  90.           NOTE: If you purchased MICRO-C as  part  of  a  "developers  kit",
  91.        refer to the documentation included with the CPU  support  files  for
  92.        details on the pre-configured library for that CPU, and the functions
  93.        available therein.
  94.     MICRO-C Library                                                  Page: 2
  95.  
  96.  
  97.     
  98.                          +----------------------------+
  99.                          |                            |
  100.                          |  ************************  |
  101.                          |  * The STANDARD library *  |
  102.                          |  ************************  |
  103.                          |                            |
  104.                          +----------------------------+
  105.     
  106.     
  107.     
  108.     
  109.     
  110.     
  111.     
  112.     
  113.     
  114.     
  115.        1.1 STANDARD Library
  116.     
  117.              The library functions described  on  the  following  pages  are
  118.           currently available in the IBM/PC MICRO-C  library  as  "standard"
  119.           functions which are of a general nature, and should be portable to
  120.           most implementations of MICRO-C.
  121.     
  122.              The exact syntax and capabilities of the  system  or  processor
  123.           dependant functions may vary  in  different  implementations,  see
  124.           your  implementation  notes  (READ.ME)  for   details.   Different
  125.           possible forms of such functions are shown using (1), (2), ...  In
  126.           these cases, the form (1) of the function is the one used  in  the
  127.           MS-DOS library.
  128.     ABORT                                                             ABORT
  129.     
  130.     
  131.     
  132.     PROTOTYPE:
  133.     
  134.         abort(char *message)
  135.     
  136.     
  137.     ARGUMENTS:
  138.     
  139.         message - Pointer to message to display
  140.     
  141.     
  142.     RETURN VALUE:
  143.     
  144.         N/A - Function never returns
  145.     
  146.     
  147.     DESCRIPTION:
  148.     
  149.           This function writes the string passed as an argument to  standard
  150.        error, and then terminates the program with a  return  code  of  '-1'
  151.        (Indicating general  failure).  This  provides  a  simple  method  of
  152.        terminating a program on an error condition with a message explaining
  153.        why.
  154.     
  155.     
  156.     EXAMPLES:
  157.     
  158.         abort("Invalid operand\n");
  159.     ABS                                                                 ABS
  160.     
  161.     
  162.     
  163.     PROTOTYPE:
  164.     
  165.         int abs(int number)
  166.     
  167.     
  168.     ARGUMENTS:
  169.     
  170.         number  - Any integer value
  171.     
  172.     
  173.     RETURN VALUE:
  174.     
  175.         The absolute value of "number"
  176.     
  177.     
  178.     DESCRIPTION:
  179.     
  180.           The "abs" function returns the absolute value of the argument.  If
  181.        "number" is a positive value, it is returned unchanged. If  negative,
  182.        the negate of that value is returned (giving a positive result).
  183.     
  184.     
  185.     EXAMPLES:
  186.     
  187.         difference = abs(value1 - value2);
  188.     ATOI                                                               ATOI
  189.     
  190.     
  191.     
  192.     PROTOTYPE:
  193.     
  194.         int atoi(char *string)
  195.     
  196.     
  197.     ARGUMENTS:
  198.     
  199.         string  - Pointer to a string containing a decimal number
  200.     
  201.     
  202.     RETURN VALUE:
  203.     
  204.         16 bit integer value
  205.     
  206.     
  207.     DESCRIPTION:
  208.     
  209.           The "atoi" function converts an ASCII string containing  a  signed
  210.        decimal number (-32768 to 32767) to a 16 bit value which is returned.
  211.        An unsigned number of the range (0 to 65535) may also  be  used,  and
  212.        the result if assigned to an "unsigned" variable will be correct.
  213.     
  214.     
  215.     EXAMPLES:
  216.     
  217.         value = atoi("1234");
  218.         value = atoi("-1");
  219.     CD                                                                   CD
  220.     
  221.     
  222.     
  223.     PROTOTYPE:
  224.     
  225.         int cd(char *pathname)
  226.     
  227.     
  228.     ARGUMENTS:
  229.     
  230.         pathname- Name of directory to make current
  231.     
  232.     
  233.     RETURN VALUE:
  234.     
  235.         0 if successful, otherwise an operating system error code
  236.     
  237.     
  238.     DESCRIPTION:
  239.     
  240.           This function sets the "current" directory, causing all subsequent
  241.        file references which do not explicitly indicate a directory path  to
  242.        access the path specified by "pathname".
  243.     
  244.     
  245.     EXAMPLES:
  246.     
  247.         cd("/mc/c_source");     /* UNIX */
  248.         cd("\\mc\\l_source");   /* MS-DOS */
  249.     CLOSE                                                             CLOSE
  250.     
  251.     
  252.     
  253.     PROTOTYPE:
  254.     
  255.         close(HANDLE fh);
  256.     
  257.     
  258.     ARGUMENTS:
  259.     
  260.         fh      - File handle of an open file
  261.     
  262.     
  263.     RETURN VALUE:
  264.     
  265.         None
  266.     
  267.     
  268.     DESCRIPTION:
  269.     
  270.           This function closes a file  which  was  previously  opened  using
  271.        "open".
  272.     
  273.     
  274.     EXAMPLES:
  275.     
  276.         close(fh);
  277.     CONCAT                                                           CONCAT
  278.     
  279.     
  280.     
  281.     PROTOTYPE:
  282.     
  283.         register concat(char *dest, char *source, ...)
  284.     
  285.     
  286.     ARGUMENTS:
  287.     
  288.         dest    - Pointer to destination string
  289.         source  - Pointer to source string
  290.         ...     - Additional sources may be given
  291.     
  292.     
  293.     RETURN VALUE:
  294.     
  295.         None
  296.     
  297.     
  298.     DESCRIPTION:
  299.     
  300.           The "concat" function concatinates the given source  strings  into
  301.        one destination string. The destination string must be  large  enough
  302.        to hold all of the source strings plus the string  terminator  (zero)
  303.        byte. No value is returned.
  304.     
  305.           NOTE: This function uses a variable number of arguments, and  must
  306.        be declared as "register" (See "stdio.h").
  307.     
  308.     
  309.     EXAMPLES:
  310.     
  311.         concat(filename,"/tmp/", input_name);
  312.     CREATE                                                           CREATE
  313.     
  314.     
  315.     
  316.     PROTOTYPE:
  317.     
  318.         int create(char *pathname, int attrs)
  319.     
  320.     
  321.     
  322.     ARGUMENTS:
  323.     
  324.         pathname- Name of file to create
  325.         attrs   - Attributes for new file
  326.     
  327.     
  328.     RETURN VALUE:
  329.     
  330.         0 if successful, otherwise an operating system error code
  331.     
  332.     
  333.     DESCRIPTION:
  334.     
  335.           The "create" function creates a new file with the specified system
  336.        attributes.
  337.     
  338.           The meaning of the individual bits in the "attrs" value is  system
  339.        dependant, and is defined in the "file.h" header file.
  340.     
  341.     
  342.     EXAMPLES:
  343.     
  344.         create("temp", HIDDEN);
  345.     DELETE                                                           DELETE
  346.     
  347.     
  348.     
  349.     PROTOTYPE:
  350.     
  351.         int delete(char *pathname)
  352.     
  353.     
  354.     
  355.     ARGUMENTS:
  356.     
  357.         pathname- Name of file to delete
  358.     
  359.     
  360.     RETURN VALUE:
  361.     
  362.         0 if successful, otherwise an operating system error code
  363.     
  364.     
  365.     DESCRIPTION:
  366.     
  367.           The "delete" function removes an existing file from the disk.  Any
  368.        disk space occupied by the file is released.
  369.     
  370.     
  371.     EXAMPLES:
  372.     
  373.         delete("temp");
  374.     EXIT                                                               EXIT
  375.     
  376.     
  377.     
  378.     PROTOTYPE:
  379.     
  380.         exit(int rc);
  381.     
  382.     
  383.     ARGUMENTS:
  384.     
  385.         rc      - Termination return code
  386.     
  387.     
  388.     RETURN VALUE:
  389.     
  390.         N/A - Function never returns
  391.     
  392.     
  393.     DESCRIPTION:
  394.     
  395.           This function terminates the execution of the program and passes a
  396.        specific return code back to the  operating  system.  A  return  code
  397.        value of zero is used  to  indicate  successful  program  completion.
  398.        Non-zero return code values may be used to indicate a particular type
  399.        of failure. A value of '-1' is often used to indicate a  non-specific
  400.        failure. Note that  the  "rc"  value  is  very  system  specific,  in
  401.        particular, some systems support only 8 bit return codes,  so  values
  402.        which are greater than 255 should be avoided.
  403.     
  404.     
  405.     EXAMPLES:
  406.     
  407.         exit(0);        /* success */
  408.         exit(-1);       /* failure */
  409.     FCLOSE                                                           FCLOSE
  410.     
  411.     
  412.     
  413.     PROTOTYPE:
  414.     
  415.         fclose(FILE *fp);
  416.     
  417.     
  418.     ARGUMENTS:
  419.     
  420.         fp      - File pointer to an open file
  421.     
  422.     
  423.     RETURN VALUE:
  424.     
  425.         None
  426.     
  427.     
  428.     DESCRIPTION:
  429.     
  430.           This function closes a file  which  was  previously  opened  using
  431.        "fopen". The I/O buffer space used by the file is  released.  In  the
  432.        case of a file open for write ('w'), the last disk buffer is  flushed
  433.        and written to disk.
  434.     
  435.     
  436.     EXAMPLES:
  437.     
  438.         fclose(fp);
  439.     FFLUSH                                                           FFLUSH
  440.     
  441.     
  442.     
  443.     PROTOTYPE:
  444.     
  445.         fflush(FILE *fp)
  446.     
  447.     
  448.     ARGUMENTS:
  449.     
  450.         fp       File pointer to an open file
  451.     
  452.     
  453.     RETURN VALUE:
  454.     
  455.         0 if successful, otherwise an operating system error code
  456.     
  457.     
  458.     DESCRIPTION:
  459.     
  460.           The "fflush" function flushes the I/O buffers for the  given  open
  461.        file. If the file is opened for WRITE, this causes any data remaining
  462.        in a partially filled output buffer to be written.  If  the  file  is
  463.        opened for READ, this has the effect of throwing away any data  which
  464.        is pending in the input buffer.
  465.     
  466.     
  467.     EXAMPLES:
  468.     
  469.         fputs("Enter you name?", stdout);
  470.         fflush(stdout);         /* Make sure prompt is output */
  471.         fgets(name, 80, stdin);
  472.     FGETS                                                             FGETS
  473.     
  474.     
  475.     
  476.     PROTOTYPE:
  477.     
  478.         char *fgets(char *buffer, int size, FILE *fp)
  479.     
  480.     
  481.     ARGUMENTS:
  482.     
  483.         buffer  - Pointer to string to receive line
  484.         size    - Maximum size of line to read
  485.         fp      - File pointer to an input file
  486.     
  487.     
  488.     RETURN VALUE:
  489.     
  490.         Pointer to "buffer", or 0 if end of file
  491.     
  492.     
  493.     DESCRIPTION:
  494.     
  495.           The "fgets" function reads characters  from  the  specified  input
  496.        file, and places them in the character  buffer  until  one  of  three
  497.        things happens:
  498.     
  499.           1) A NEWLINE character is encountered.
  500.     
  501.           2) The END of the file is encountered.
  502.     
  503.           3) The limit of "size" character is read.
  504.     
  505.           The string is terminated with the standard  NULL  (00)  character.
  506.        The trailing NEWLINE '\n' character is NOT  included  in  the  output
  507.        buffer.
  508.     
  509.     
  510.     EXAMPLES:
  511.     
  512.         fgets(input_line, 80, input_file);
  513.     FIND_FIRST                                                   FIND_FIRST
  514.     
  515.     
  516.     
  517.     PROTOTYPE:
  518.     
  519.         int find_first(char *pattern, int mattrs, char name[], int &sizeh,
  520.                        int &sizel, int &attrs, int &time, int &date)
  521.     
  522.     
  523.     ARGUMENTS:
  524.     
  525.         pattern - File name pattern to match
  526.         mattrs  - File attributes to match
  527.         name    - Address of string to receive file name
  528.         &sizeh  - Address of int to receive high word of size
  529.         &sizel  - Address of int to receive low word of size
  530.         &attrs  - Address of int to receive attributes
  531.         &time   - Address of int to receive time stamp
  532.         &date   - Address of int to receive date stamp
  533.     
  534.     
  535.     RETURN VALUE:
  536.     
  537.         0 if successful, otherwise an operating system error code
  538.     
  539.     
  540.     DESCRIPTION:
  541.     
  542.           This function locates the first file on the disk which matches the
  543.        given pattern. The "mattrs" field specifies  any  special  attributes
  544.        the files must have  in  order  to  be  matched,  use  0  for  normal
  545.        directory searches.
  546.     
  547.           Subsequent files may be located using the "find_next" function.
  548.     
  549.           The above function prototype describes the  MS-DOS  implementation
  550.        of the function. With other operating systems, the function may  have
  551.        slightly  different  parameters,   due   to   differing   information
  552.        available. See your implementation notes.
  553.     
  554.     
  555.     EXAMPLES:
  556.     
  557.         if(find_first(pattern, 0, name, &sh, &sl, &a, &t, &d))
  558.             abort("No matching files found\n");
  559.     FIND_NEXT                                                     FIND_NEXT
  560.     
  561.     
  562.     
  563.     PROTOTYPE:
  564.     
  565.         int find_next(char name[], int &sizeh, int &sizel, int &attrs,
  566.                       int &time, int &date)
  567.     
  568.     
  569.     ARGUMENTS:
  570.     
  571.         name    - Address of string to receive file name
  572.         &sizeh  - Address of int to receive high word of size
  573.         &sizel  - Address of int to receive low word of size
  574.         &attrs  - Address of int to receive attributes
  575.         &time   - Address of int to receive time stamp
  576.         &date   - Address of int to receive date stamp
  577.     
  578.     
  579.     RETURN VALUE:
  580.     
  581.         0 if successful, otherwise an operating system error code
  582.     
  583.     
  584.     DESCRIPTION:
  585.     
  586.           The function must be preceeded by a call to "find_first", and will
  587.        locate the next file on  the  disk  which  matches  the  pattern  and
  588.        attributes given to that function call.
  589.     
  590.           The above function prototype describes the  MS-DOS  implementation
  591.        of the function. With other operating systems, the function may  have
  592.        slightly  different  parameters,   due   to   differing   information
  593.        available. See your implementation notes.
  594.     
  595.     
  596.     EXAMPLES:
  597.     
  598.         do
  599.             printf("%s\n", name);
  600.         while(!find_next(name, &sh, &sl, &a, &t, &d));
  601.     FOPEN                                                             FOPEN
  602.     
  603.     
  604.     
  605.     PROTOTYPE:
  606.     
  607.         FILE *fopen(char *filename, char *options)
  608.     
  609.     
  610.     ARGUMENTS:
  611.     
  612.         filename- Name of the file to open
  613.         options - String containing open options:
  614.                     'a' - Append to file (must use with 'w')
  615.                     'b' - Binary mode (default is text)
  616.                     'q' - Quit { exit(-1) } on failure
  617.                     'r' - Open file for read
  618.                     'v' - Issue error message on failure
  619.                     'w' - Open file for write
  620.     
  621.     
  622.     RETURN VALUE:
  623.     
  624.         File pointer to the file buffer for the open file
  625.         Zero (0) if file could not be opened
  626.     
  627.     
  628.     DESCRIPTION:
  629.     
  630.           This function opens a file for  buffered  input  ('r')  or  output
  631.        ('w'), allowing subsequent I/O operations to read or write the  file.
  632.        If the 'b' option is NOT included, the file is assumed to be  a  TEXT
  633.        file, and appropriate translations  are  made  for  NEWLINE  and  EOF
  634.        interpretation.
  635.     
  636.           The size of the I/O buffer used is established by "fopen" from the
  637.        external variable 'IOB_size',  which  has  a  default  value  of  256
  638.        (bytes). This variable is defined in the 'file.h'  header  file,  and
  639.        may be modified prior to calling this function if you wish to  use  a
  640.        different buffer size.
  641.     
  642.           One I/O buffer is allocated from the heap for each open file. When
  643.        using a large IOB_size value, you must be careful not to consume more
  644.        memory than is available.
  645.     
  646.     
  647.     EXAMPLES:
  648.     
  649.         fp = fopen("input_file", "r");
  650.         fp = fopen("input_file", "rvq");
  651.         IOB_size = 1024*10;         /* Set up a 10K buffer */
  652.         fp = fopen("output_file", "wb");
  653.     FPRINTF                                                         FPRINTF
  654.     
  655.     
  656.     
  657.     PROTOTYPE:
  658.     
  659.         register fprintf(FILE *fp, char *format, arg, ...)
  660.     
  661.     
  662.     ARGUMENTS:
  663.     
  664.         fp      - File pointer to an output file
  665.         format  - Pointer to format string
  666.         arg     - Argument as determined by format string
  667.         ...     - Additional arguments may be required
  668.     
  669.     
  670.     RETURN VALUE:
  671.     
  672.         None
  673.     
  674.     
  675.     DESCRIPTION:
  676.     
  677.           This routine performs a formatted print to  a  file  specified  by
  678.        'fp'. The 'format' string is written to the file with  the  arguments
  679.        substituted for special "conversion  characters".  These  "conversion
  680.        characters" are identified by a preceeding '%', and may be one of the
  681.        following:
  682.     
  683.                     b       - Binary number
  684.                     c       - Character
  685.                     d       - Decimal (signed) number
  686.                     o       - Octal number
  687.                     s       - String
  688.                     u       - Unsigned decimal number
  689.                     x       - Hexidecimal number
  690.                     %       - A single percent sign (No argument used)
  691.     
  692.           A numeric "field width" specifier may be placed in between the '%'
  693.        and the conversion character, in which case the value will be  output
  694.        in a field of that width. If the "field width" is a negative  number,
  695.        the output will be left justified in the field, otherwise it is right
  696.        justified. If the field width contains a leading '0', then the output
  697.        field will be padded with zero's, otherwise spaces are used.
  698.     
  699.           If no "field width" is given, the output  is  free  format,  using
  700.        only as much space as required.
  701.     
  702.           NOTE: This function uses a variable number of arguments, and  must
  703.        be declared as "register" (See "stdio.h").
  704.     
  705.     
  706.     EXAMPLES:
  707.     
  708.         fprintf(stderr,"Filename='%s'\n", filename);
  709.         fprintf(stdout,"Address=%04x\n", address);
  710.         fprintf(outfile,"Amount: $%3u.%02u\n", amount / 100, amount % 100);
  711.     FPUTS                                                             FPUTS
  712.     
  713.     
  714.     
  715.     PROTOTYPE:
  716.     
  717.         fputs(char *string, FILE *fp)
  718.     
  719.     
  720.     ARGUMENTS:
  721.     
  722.         string  - Pointer to a character string
  723.         fp      - FIle pointer to output file
  724.     
  725.     
  726.     RETURN VALUE:
  727.     
  728.         0 if successful, otherwise an operating system error code
  729.     
  730.     
  731.     DESCRIPTION:
  732.     
  733.           The "fputs" function writes the specified string to the  indicated
  734.        output file. The zero terminating the string is NOT written.
  735.     
  736.     
  737.     EXAMPLES:
  738.     
  739.         fputs("Text message", output_file);
  740.     FREAD                                                             FREAD
  741.     
  742.     
  743.     
  744.     PROTOTYPE:
  745.     
  746.         int fread(char *buffer, int size, FILE *fp)
  747.     
  748.     
  749.     ARGUMENTS:
  750.     
  751.         buffer  - Pointer to buffer to receive data
  752.         size    - Number of bytes to read
  753.         fp      - File pointer to an input file
  754.     
  755.     
  756.     RETURN VALUE:
  757.     
  758.         Number of bytes read from file
  759.     
  760.     
  761.     DESCRIPTION:
  762.     
  763.           This function reads a block of data from a file and places  it  in
  764.        memory at the address of "buffer". Data will be read in  either  TEXT
  765.        or BINARY form, depending on how the file was opened. If  the  number
  766.        of bytes returned is less than the number of bytes requested,  either
  767.        the end of the file was encountered or an error condition occured (in
  768.        which case the value will be zero).
  769.     
  770.     
  771.     EXAMPLES:
  772.     
  773.         fread(block, 512, input_fp);
  774.     FREE                                                               FREE
  775.     
  776.     
  777.     
  778.     PROTOTYPE:
  779.     
  780.         free(char *ptr)
  781.     
  782.     
  783.     ARGUMENTS:
  784.     
  785.         ptr     - Pointer to a previously allocated memory block
  786.     
  787.     
  788.     RETURN VALUE:
  789.     
  790.         None
  791.     
  792.     
  793.     DESCRIPTION:
  794.     
  795.           The "free" function releases (de-allocates) a block of memory that
  796.        was obtained via a call to "malloc", and returns it to the heap. This
  797.        makes it available for use by other memory allocations.
  798.     
  799.     
  800.     EXAMPLES:
  801.     
  802.         if(!(ptr = malloc(BUFSIZ)))     /* Allocate a temporary buffer */
  803.             abort("Not enough memory");
  804.         do {                            /* Copy the file over */
  805.             size = fread(ptr, BUFSIZ, in_fp);
  806.             fwrite(ptr, size, out_fp); }
  807.         while(size == BUFSIZ);
  808.         free(ptr);                      /* Release temporary buffer */
  809.     FSCANF                                                           FSCANF
  810.     
  811.     
  812.     
  813.     PROTOTYPE:
  814.     
  815.         register int fscanf(FILE *fp, char *format, &arg, ...)
  816.     
  817.     
  818.     ARGUMENTS:
  819.     
  820.         fp      - File pointer to an input file
  821.         format  - Pointer to format string
  822.         arg     - Argument as determined by format string
  823.         ...     - Additional arguments may be required
  824.     
  825.     
  826.     RETURN VALUE:
  827.     
  828.         The number of successful matches
  829.         EOF (-1) if end of file or an error condition occurs
  830.     
  831.     
  832.     DESCRIPTION:
  833.     
  834.           This routine reads a line from the specified file and scans it for
  835.        specific values which  are  then  assigned  to  the  passed  argument
  836.        addresses. The types of values  scanned  are  determined  by  special
  837.        "conversion characters" within the "format" string. These "conversion
  838.        characters" are identified by a preceeding '%', and may be one of the
  839.        following:
  840.     
  841.                     b       - Binary number
  842.                     c       - Character
  843.                     d       - Decimal (signed) number
  844.                     o       - Octal number
  845.                     s       - String
  846.                     u       - Unsigned decimal number
  847.                     x       - Hexidecimal number
  848.                     %       - A single percent sign (No argument used)
  849.     
  850.           Before scanning for  any  value,  any  leading  "space"  or  "tab"
  851.        characters in the input line are automatically flushed.
  852.     
  853.           Scanning of a particular value type will terminate when either the
  854.        end of  the  line  or  a  non-applicible  character  is  encountered.
  855.        Scanning of strings (%s) stops with a "space" or "tab" character, and
  856.        the stored string will be zero terminated.
  857.     
  858.           A numeric "field width" specifier may be placed in between the '%'
  859.        and the conversion character, in which case  scanning  of  the  value
  860.        will  also  terminate  if  that  many  input  characters  have   been
  861.        processed.
  862.     
  863.           Scanning  for  characters  (%c)  assumes  a  "field  width"  of  1
  864.        character (%1c) unless it is otherwise specified.
  865.     
  866.     
  867.     
  868.     
  869.     
  870.     
  871.     
  872.     
  873.     
  874.     
  875.           Any other (non-conversion) characters in the  format  string  will
  876.        cause the next character in the input string which is not  a  "space"
  877.        or "tab" to be skipped if it matches that character.
  878.     
  879.           Any variable values from the input line  which  are  not  required
  880.        must be cleared by scanning them into a "dummy" variable.
  881.     
  882.           The most common mistake when using "fscanf" is forgetting  to  use
  883.        the '&'  operator  with  a  simple  variable  argument.  This  causes
  884.        "fscanf" to store the value INDIRECTLY at the  address  contained  in
  885.        that variable (Similar to  using  '*'  with  a  pointer)  instead  of
  886.        storing the value into the actual variable  itself.  Arguments  which
  887.        are array names do not require the '&' operator, since the address of
  888.        the array is already generated by reference to its name.
  889.     
  890.           Unlike "fscanf" in most  other  compiler  libraries,  the  MICRO-C
  891.        function always reads and scans a single line from the input file.
  892.     
  893.           NOTE: This function uses a variable number of arguments, and  must
  894.        be declared as "register".
  895.     
  896.     
  897.     EXAMPLES:
  898.     
  899.         if(fscanf(infile,"%s %s %u", first_name, last_name, &age) != 3)
  900.             abort("Error in user record\n");
  901.     FSEEK                                                             FSEEK
  902.     
  903.     
  904.     
  905.     PROTOTYPE:
  906.     
  907.         (1) int fseek(FILE *fp, int h_offset, unsigned l_offset, int mode)
  908.         (2) int fseek(FILE *fp, int offset, mode)
  909.     
  910.     
  911.     ARGUMENTS:
  912.     
  913.         fp      - File pointer to an open file
  914.         h_offset- Highest 16 bits of offset value
  915.         l_offset- Lowest 16 bits of offset value
  916.         offset  - 16 bit offset value
  917.         mode    - Type of seek
  918.                     0 = Absolute from start of file
  919.                     1 = Signed offset from current position
  920.                     2 = Signed offset from end of file
  921.     
  922.     
  923.     RETURN VALUE:
  924.     
  925.         0 if successful, otherwise an operating system error code
  926.     
  927.     
  928.     DESCRIPTION:
  929.     
  930.           This function positions the operating system internal pointer into
  931.        a file so that any read or write will take  place  at  the  specified
  932.        position in the file.
  933.     
  934.           Most operating systems which support files of > 64K bytes in  size
  935.        will support form (1) of the function, using both high and low offset
  936.        values.
  937.     
  938.           Smaller operating  systems  may  only  support  form  (2)  of  the
  939.        function, allowing seeking of only +/- 32K bytes.
  940.     
  941.           Also, some implementations may not support  all  "modes",  or  may
  942.        only allow unsigned (positive) offsets.
  943.     
  944.     
  945.     EXAMPLES:
  946.     
  947.         fseek(in_file, 0, 2);   /* Advance to end of file */
  948.     FTELL                                                             FTELL
  949.     
  950.     
  951.     
  952.     PROTOTYPE:
  953.     
  954.         (1) int ftell(FILE *fp, int &h_offset, unsigned &l_offset)
  955.         (2) int ftell(FILE *fp, int &offset)
  956.     
  957.     
  958.     ARGUMENTS:
  959.     
  960.         fp      - File pointer to an open file
  961.         h_offset- Address of int to receive high word of offset
  962.         l_offset- Address of int to receive low word of offset
  963.         offset  - Address of int to receive offset
  964.     
  965.     
  966.     RETURN VALUE:
  967.     
  968.         0 if successful, otherwise an operating system error code
  969.     
  970.     
  971.     DESCRIPTION:
  972.     
  973.           This function gets the current read/write position within a  file.
  974.        The position returned indicates the absolute character (byte)  offset
  975.        from the start of the file where the next read  or  write  will  take
  976.        place.
  977.     
  978.           Most operating systems which support files of > 64K bytes in  size
  979.        will support form (1) of the function, returning both  high  and  low
  980.        offset values.
  981.     
  982.           Smaller operating  systems  may  only  support  form  (2)  of  the
  983.        function,  allowing  access  to  only  the  first   65535   character
  984.        positions.
  985.     
  986.     
  987.     EXAMPLES:
  988.     
  989.         ftell(fp, &oldh, &oldl);    /* Save file position */
  990.             . . .                   /* Perform some operations on the file */
  991.         fseek(fp, oldh, oldl, 0);   /* Return to previous position */
  992.     FWRITE                                                           FWRITE
  993.     
  994.     
  995.     
  996.     PROTOTYPE:
  997.     
  998.         int fwrite(char *block, int size, FILE *fp)
  999.     
  1000.     
  1001.     ARGUMENTS:
  1002.     
  1003.         block   - Pointer to a block of data to write
  1004.         size    - Number of bytes to write
  1005.         fp      - File pointer to an output file
  1006.     
  1007.     
  1008.     RETURN VALUE:
  1009.     
  1010.         0 if successful, otherwise an operating system error code
  1011.     
  1012.     
  1013.     DESCRIPTION:
  1014.     
  1015.           This function writes a block of data to the  indicated  file  from
  1016.        memory at the specified address. Data is written in  either  TEXT  or
  1017.        BINARY mode, depending on how the  file  was  opened.  If  the  value
  1018.        returned is less than the value of the "size" parameter,  some  error
  1019.        condition has occured (Such as disk full).
  1020.     
  1021.     
  1022.     EXAMPLES:
  1023.     
  1024.         if(fwrite(buffer, 100, fp) < 100)
  1025.             abort("File write error\n");
  1026.     GETC                                                               GETC
  1027.     
  1028.     
  1029.     
  1030.     PROTOTYPE:
  1031.     
  1032.         int getc(FILE *fp)
  1033.     
  1034.     
  1035.     ARGUMENTS:
  1036.     
  1037.         fp      - File pointer to an input file
  1038.     
  1039.     
  1040.     RETURN VALUE:
  1041.     
  1042.         Value of a character read from the file (0-255)
  1043.         EOF (-1) if end of file or an error condition occurs
  1044.     
  1045.     
  1046.     DESCRIPTION:
  1047.     
  1048.           This function reads a single character from  an  input  file,  and
  1049.        returns it as a positive value in the range of 0 to 255.  A  full  16
  1050.        bit value is returned, allowing the  end  of  file  condition  to  be
  1051.        distinct from the character value 255.
  1052.     
  1053.     
  1054.     EXAMPLES:
  1055.     
  1056.         if((c = getc(input_file)) == EOF)
  1057.             abort("End of file encountered\n");
  1058.     GETDIR                                                           GETDIR
  1059.     
  1060.     
  1061.     
  1062.     PROTOTYPE:
  1063.     
  1064.         int getdir(char pathname[])
  1065.     
  1066.     
  1067.     ARGUMENTS:
  1068.     
  1069.         pathname- Address of string to receive directory path
  1070.     
  1071.     
  1072.     RETURN VALUE:
  1073.     
  1074.         0 if successful, otherwise an operating system error code
  1075.     
  1076.     
  1077.     DESCRIPTION:
  1078.     
  1079.           This function retreives from the system the name of the  "current"
  1080.        directory path.
  1081.     
  1082.           The "pathname" string must be long  enough  to  hold  the  largest
  1083.        pathname supported by the system, as  indicated  by  the  "PATH_SIZE"
  1084.        definition in the "file.h" header file.
  1085.     
  1086.     
  1087.     EXAMPLES:
  1088.     
  1089.         getdir(¤t_dir);
  1090.     GETENV                                                           GETENV
  1091.     
  1092.     
  1093.     
  1094.     PROTOTYPE:
  1095.     
  1096.         int getenv(char *ename, char *dest)
  1097.     
  1098.     
  1099.     ARGUMENTS:
  1100.     
  1101.         ename   - String containing name of environment variable
  1102.         dest    - Buffer to receive variable string value
  1103.     
  1104.     
  1105.     RETURN VALUE:
  1106.     
  1107.         1 if environment variable was found, 0 if not.
  1108.     
  1109.     
  1110.     DESCRIPTION:
  1111.     
  1112.           The GETENV function gets the value of a variable in  the  programs
  1113.        environment, and returns it as a string. If the environment  variable
  1114.        is not found, zero is returned, and the destination buffer is set  to
  1115.        a null (zero length) string.
  1116.     
  1117.           Use of this  function  allows  a  programs  fixed  parameters  and
  1118.        options to be specified once in environment variables, which may then
  1119.        be extracted by the program, eliminating the need  to  specify  those
  1120.        values every time the program is executed.
  1121.     
  1122.           When operating  MICRO-C  under  operating  systems  which  do  not
  1123.        support environment variables, this function will not be available.
  1124.     
  1125.     
  1126.     EXAMPLES:
  1127.     
  1128.         if(!getenv("COMSPEC", command))
  1129.             abort("No command processor defined\n");
  1130.     IN                                                                   IN
  1131.     
  1132.     
  1133.     
  1134.     PROTOTYPE:
  1135.     
  1136.         int in(unsigned port)
  1137.     
  1138.     
  1139.     ARGUMENTS:
  1140.     
  1141.         port    - I/O port address
  1142.     
  1143.     
  1144.     RETURN VALUE:
  1145.     
  1146.         The 8 bit value read from the given I/O port address
  1147.     
  1148.     
  1149.     DESCRIPTION:
  1150.     
  1151.           The "in" function reads and returns a byte (8 bits)  from  an  I/O
  1152.        port as an integer value between 0 and 255.
  1153.     
  1154.           The valid range of values for "port" depends on  the  I/O  address
  1155.        space of the processor.
  1156.     
  1157.           This function is not provided for processors which do not  support
  1158.        a separate I/O address space.
  1159.     
  1160.     
  1161.     EXAMPLES:
  1162.     
  1163.         while(in(0));   /* Wait for flag to clear */
  1164.     INW                                                                 INW
  1165.     
  1166.     
  1167.     
  1168.     PROTOTYPE:
  1169.     
  1170.         int inw(unsigned port)
  1171.     
  1172.     
  1173.     ARGUMENTS:
  1174.     
  1175.         port    - I/O port address
  1176.     
  1177.     
  1178.     RETURN VALUE:
  1179.     
  1180.         The 16 bit value read from the given I/O port address
  1181.     
  1182.     
  1183.     DESCRIPTION:
  1184.     
  1185.           The "inw" function reads and returns a word (16 bits) from an  I/O
  1186.        port as an integer value between 0 and 65535 (-1).
  1187.     
  1188.           The valid range of values for "port" depends on  the  I/O  address
  1189.        space of the processor.
  1190.     
  1191.           This function is not provided for processors which do not  support
  1192.        a separate I/O address space.
  1193.     
  1194.     
  1195.     EXAMPLES:
  1196.     
  1197.         var = inw(0);
  1198.     ISALNUM                                                         ISALNUM
  1199.     
  1200.     
  1201.     
  1202.     PROTOTYPE:
  1203.     
  1204.         int isalnum(char c)
  1205.     
  1206.     
  1207.     ARGUMENTS:
  1208.     
  1209.         c       - Any character value
  1210.     
  1211.     
  1212.     RETURN VALUE:
  1213.     
  1214.         1 if 'c' is alphabetic or numeric
  1215.         0 if 'c' is not alphabetic or numeric
  1216.     
  1217.     
  1218.     DESCRIPTION:
  1219.     
  1220.           Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
  1221.        alphabetic letter in either upper or  lower  case  or  if  'c'  is  a
  1222.        numeric digit, otherwise FALSE (0) is returned.
  1223.     
  1224.     
  1225.     EXAMPLES:
  1226.     
  1227.         while(isalnum(*ptr))        /* Copy over symbol name */
  1228.             *name++ = *ptr++;
  1229.     ISALPHA                                                         ISALPHA
  1230.     
  1231.     
  1232.     
  1233.     PROTOTYPE:
  1234.     
  1235.         int isalpha(char c)
  1236.     
  1237.     
  1238.     ARGUMENTS:
  1239.     
  1240.         c       - Any character value
  1241.     
  1242.     
  1243.     RETURN VALUE:
  1244.     
  1245.         1 if 'c' is alphabetic
  1246.         0 if 'c' is not alphabetic
  1247.     
  1248.     
  1249.     DESCRIPTION:
  1250.     
  1251.           Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
  1252.        alphabetic letter in either upper or lower case, otherwise FALSE  (0)
  1253.        is returned.
  1254.     
  1255.     
  1256.     EXAMPLES:
  1257.     
  1258.         flag = isalpha(input_char);
  1259.     ISCNTRL                                                         ISCNTRL
  1260.     
  1261.     
  1262.     
  1263.     PROTOTYPE:
  1264.     
  1265.         int iscntrl(char c)
  1266.     
  1267.     
  1268.     ARGUMENTS:
  1269.     
  1270.         c       - Any character value
  1271.     
  1272.     
  1273.     RETURN VALUE:
  1274.     
  1275.         1 if 'c' is a "control" character
  1276.         0 if 'c' is not a "control" character
  1277.     
  1278.     
  1279.     DESCRIPTION:
  1280.     
  1281.           Returns TRUE (1) is the passed character 'c' is an ASCII "control"
  1282.        character (0x00-0x1F or 0x7F), otherwise FALSE (0) is returned.
  1283.     
  1284.     
  1285.     EXAMPLES:
  1286.     
  1287.         putc(iscntrl(c) ? '.' : c, stdout); /* Display controls as '.' */
  1288.     ISDIGIT                                                         ISDIGIT
  1289.     
  1290.     
  1291.     
  1292.     PROTOTYPE:
  1293.     
  1294.         int isdigit(char c)
  1295.     
  1296.     
  1297.     ARGUMENTS:
  1298.     
  1299.         c       - Any character value
  1300.     
  1301.     
  1302.     RETURN VALUE:
  1303.     
  1304.         1 if 'c' is numeric
  1305.         0 if 'c' is not numeric
  1306.     
  1307.     
  1308.     DESCRIPTION:
  1309.     
  1310.           Returns TRUE (1) is the passed character 'c'  is  an  ASCII  digit
  1311.        ('0'-'9'), otherwise FALSE (0) is returned.
  1312.     
  1313.     
  1314.     EXAMPLES:
  1315.     
  1316.         value = 0;
  1317.         while(isdigit(*ptr))
  1318.             value = (value * 10) + (*ptr++ - '0');
  1319.     ISGRAPH                                                         ISGRAPH
  1320.     
  1321.     
  1322.     
  1323.     PROTOTYPE:
  1324.     
  1325.         int isgraph(char c)
  1326.     
  1327.     
  1328.     ARGUMENTS:
  1329.     
  1330.         c       - Any character value
  1331.     
  1332.     
  1333.     RETURN VALUE:
  1334.     
  1335.         1 if 'c' is a non-space printable character
  1336.         0 if 'c' is a space or not printable
  1337.     
  1338.     
  1339.     DESCRIPTION:
  1340.     
  1341.           Returns TRUE (1) if the passed character 'c' is a printable  ASCII
  1342.        character other than  a  space  character,  otherwise  FALSE  (0)  is
  1343.        returned.
  1344.     
  1345.     
  1346.     EXAMPLES:
  1347.     
  1348.         putc(isgraph(c) ? c : '.', stdout);
  1349.     ISLOWER                                                         ISLOWER
  1350.     
  1351.     
  1352.     
  1353.     PROTOTYPE:
  1354.     
  1355.         int islower(char c)
  1356.     
  1357.     
  1358.     ARGUMENTS:
  1359.     
  1360.         c       - Any character value
  1361.     
  1362.     
  1363.     RETURN VALUE:
  1364.     
  1365.         1 if 'c' is lower case alphabetic
  1366.         0 if 'c' is not lower case alphabetic
  1367.     
  1368.     
  1369.     DESCRIPTION:
  1370.     
  1371.           Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
  1372.        alphabetic letter of lower case, otherwise FALSE (0) is returned.
  1373.     
  1374.     
  1375.     EXAMPLES:
  1376.     
  1377.         flag = islower(input_char);
  1378.     ISPUNCT                                                         ISPUNCT
  1379.     
  1380.     
  1381.     
  1382.     PROTOTYPE:
  1383.     
  1384.         int ispunct(char c)
  1385.     
  1386.     
  1387.     ARGUMENTS:
  1388.     
  1389.         c       - Any character value
  1390.     
  1391.     
  1392.     RETURN VALUE:
  1393.     
  1394.         1 if 'c' is a printable non-alphanumeric character
  1395.         0 if 'c' is not printable or alphanumeric
  1396.     
  1397.     
  1398.     DESCRIPTION:
  1399.     
  1400.           Returns TRUE (1) if the passed character 'c' is a printable  ASCII
  1401.        character which is not a letter of the alphabet or a  numeric  digit,
  1402.        otherwise FALSE (0) is returned.
  1403.     
  1404.     
  1405.     EXAMPLES:
  1406.     
  1407.         while(ispunct(*ptr))
  1408.             ++ptr;
  1409.     ISSPACE                                                         ISSPACE
  1410.     
  1411.     
  1412.     
  1413.     PROTOTYPE:
  1414.     
  1415.         int isspace(char c)
  1416.     
  1417.     
  1418.     ARGUMENTS:
  1419.     
  1420.         c       - Any character value
  1421.     
  1422.     
  1423.     RETURN VALUE:
  1424.     
  1425.         1 if 'c' is a space character (space, tab or newline)
  1426.         0 if 'c' is not a space character
  1427.     
  1428.     
  1429.     DESCRIPTION:
  1430.     
  1431.           Returns TRUE (1) if the passed character 'c' is one  of  a  space,
  1432.        tab or newline, otherwise FALSE (0) is returned.
  1433.     
  1434.     
  1435.     EXAMPLES:
  1436.     
  1437.         while(isspace(*ptr))
  1438.             ++ptr;
  1439.     ISUPPER                                                         ISUPPER
  1440.     
  1441.     
  1442.     
  1443.     PROTOTYPE:
  1444.     
  1445.         int isupper(char c)
  1446.     
  1447.     
  1448.     ARGUMENTS:
  1449.     
  1450.         c       - Any character value
  1451.     
  1452.     
  1453.     RETURN VALUE:
  1454.     
  1455.         1 if 'c' is upper case alphabetic
  1456.         0 if 'c' is not upper case alphabetic
  1457.     
  1458.     
  1459.     DESCRIPTION:
  1460.     
  1461.           Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
  1462.        alphabetic letter of upper case, otherwise FALSE (0) is returned.
  1463.     
  1464.     
  1465.     EXAMPLES:
  1466.     
  1467.         flag = isupper(input_char);
  1468.     LGETC                                                             LGETC
  1469.     
  1470.     
  1471.     
  1472.     PROTOTYPE:
  1473.     
  1474.         int lgetc(HANDLE fh)
  1475.     
  1476.     
  1477.     ARGUMENTS:
  1478.     
  1479.         fh      - File handle for an input file
  1480.     
  1481.     
  1482.     RETURN VALUE:
  1483.     
  1484.         Value of a character read from the file (0-255)
  1485.         EOF (-1) if end of file or an error condition occurs
  1486.     
  1487.     
  1488.     DESCRIPTION:
  1489.     
  1490.           This function reads a single character from an  input  file  using
  1491.        LOW LEVEL (unbuffered) I/O, and returns it as a positive value in the
  1492.        range of 0 to 255. A full 16 bit value is returned, allowing the  end
  1493.        of file condition to be distinct from the character value 255.
  1494.     
  1495.     
  1496.     EXAMPLES:
  1497.     
  1498.         if((c = lgetc(input_file)) == EOF)
  1499.             abort("End of file encountered\n");
  1500.     LGETS                                                             LGETS
  1501.     
  1502.     
  1503.     
  1504.     PROTOTYPE:
  1505.     
  1506.         char *lgets(char *buffer, int size, HANDLE fh)
  1507.     
  1508.     
  1509.     ARGUMENTS:
  1510.     
  1511.         buffer  - Pointer to string to receive line
  1512.         size    - Maximum size of line to read
  1513.         fh      - File handle of an input file
  1514.     
  1515.     
  1516.     RETURN VALUE:
  1517.     
  1518.         Pointer to "buffer", or 0 if end of file
  1519.     
  1520.     
  1521.     DESCRIPTION:
  1522.     
  1523.           The "lgets" function reads characters  from  the  specified  input
  1524.        file using LOW  LEVEL  (unbuffered)  I/O,  and  places  them  in  the
  1525.        character buffer until one of three things happens:
  1526.     
  1527.           1) A NEWLINE character is encountered.
  1528.     
  1529.           2) The END of the file is encountered.
  1530.     
  1531.           3) The limit of "size" characters are read.
  1532.     
  1533.           The string is terminated with the standard  NULL  (00)  character.
  1534.        The trailing NEWLINE '\n' character is NOT  included  in  the  output
  1535.        buffer.
  1536.     
  1537.     
  1538.     EXAMPLES:
  1539.     
  1540.         lgets(input_line, 80, L_stdin);
  1541.     LPUTC                                                             LPUTC
  1542.     
  1543.     
  1544.     
  1545.     PROTOTYPE:
  1546.     
  1547.         lputc(char c, HANDLE fh)
  1548.     
  1549.     
  1550.     ARGUMENTS:
  1551.     
  1552.         c       - Any character value
  1553.         fh      - File handle of an output file
  1554.     
  1555.     
  1556.     RETURN VALUE:
  1557.     
  1558.         0 if successful, otherwise an operating system error code
  1559.     
  1560.     
  1561.     DECRIPTION:
  1562.     
  1563.           This function writes the character 'c' to the  file  indicated  by
  1564.        'fh'. The "newline" (\n) character will be translated  into  whatever
  1565.        character(s) are required by the operating system to separate records
  1566.        in the file.
  1567.     
  1568.     
  1569.     EXAMPLES:
  1570.     
  1571.         lputc('*', fh);
  1572.         lputc('\n', L_stderr);
  1573.     LPUTS                                                             LPUTS
  1574.     
  1575.     
  1576.     
  1577.     PROTOTYPE:
  1578.     
  1579.         lputs(char *string, HANDLE fh)
  1580.     
  1581.     
  1582.     ARGUMENTS:
  1583.     
  1584.         string  - Pointer to a character string
  1585.         fh      - File handle of an output file
  1586.     
  1587.     
  1588.     RETURN VALUE:
  1589.     
  1590.         0 if successful, otherwise an operating system error code
  1591.     
  1592.     
  1593.     DESCRIPTION:
  1594.     
  1595.           The "lputs" function writes the specified string to the  indicated
  1596.        output file using LOW LEVEL (unbuffered) I/O.  The  zero  terminating
  1597.        the string is NOT written.
  1598.     
  1599.     
  1600.     EXAMPLES:
  1601.     
  1602.         lputs("Text message", output_fh);
  1603.     LONGJMP                                                         LONGJMP
  1604.     
  1605.     
  1606.     
  1607.     PROTOTYPE:
  1608.     
  1609.         longjmp(int savenv[3], int rvalue)
  1610.     
  1611.     
  1612.     ARGUMENTS:
  1613.     
  1614.         savenv  - Save area for program context
  1615.         rvalue  - Value to be returned by "setjmp"
  1616.     
  1617.     
  1618.     RETURN VALUE:
  1619.     
  1620.         N/A - Function never returns
  1621.     
  1622.     
  1623.     DESCRIPTION:
  1624.     
  1625.           The  "longjmp"  function  causes  execution  to  transfer  to  the
  1626.        "setjmp" call which  set  up  the  "savenv"  variable.  The  "setjmp"
  1627.        function will appear to return the value of "rvalue".
  1628.     
  1629.           NOTE-1: "longjmp" may  only  be  used  from  within  the  function
  1630.        calling "setjmp" or a function which has been called  "beneath"  that
  1631.        function. IT MUST NOT BE USED AFTER THE FUNCTION CALLING "SETJMP" HAS
  1632.        TERMINATED.
  1633.     
  1634.           NOTE-2: If "rvalue" is zero, the function  calling  "setjmp"  will
  1635.        assume that it is returning from initialization. Unless you want this
  1636.        unusual behavior, you should not pass  a  return  value  of  zero  to
  1637.        "longjmp".
  1638.     
  1639.           See also SETJMP.
  1640.     
  1641.     
  1642.     EXAMPLES:
  1643.     
  1644.         if(getc(stdin) == ('C'-'@'))    /* If Control-C entered... */
  1645.             longjmp(savearea, 1);       /* Return to main function */
  1646.     LREWIND                                                         LREWIND
  1647.     
  1648.     
  1649.     
  1650.     PROTOTYPE:
  1651.     
  1652.         int lrewind(HANDLE fh)
  1653.     
  1654.     
  1655.     ARGUMENTS:
  1656.     
  1657.         fh      - File handle of an open file
  1658.     
  1659.     
  1660.     RETURN VALUE:
  1661.     
  1662.         0 if successful, otherwise an operating system error code
  1663.     
  1664.     
  1665.     DESCRIPTION:
  1666.     
  1667.           This function resets the operating system internal file handle  so
  1668.        than any subsequent read or writes will be at the  beginning  of  the
  1669.        file. For use with LOW LEVEL (unbuffered) file I/O only.
  1670.     
  1671.     
  1672.     EXAMPLES:
  1673.     
  1674.         lrewind(input_fh);
  1675.     LSEEK                                                             LSEEK
  1676.     
  1677.     
  1678.     
  1679.     PROTOTYPE:
  1680.     
  1681.         (1) int lseek(HANDLE fh, int h_offset, unsigned l_offset, int mode)
  1682.         (2) int lseek(HANDLE fh, int offset, mode)
  1683.     
  1684.     
  1685.     ARGUMENTS:
  1686.     
  1687.         fh  - File handle of an open file
  1688.         h_offset- Highest 16 bits of offset value
  1689.         l_offset- Lowest 16 bits of offset value
  1690.         offset  - 16 bit offset value
  1691.         mode    - Type of seek
  1692.                     0 = Absolute from start of file
  1693.                     1 = Signed offset from current position
  1694.                     2 = Signed offset from end of file
  1695.     
  1696.     
  1697.     RETURN VALUE:
  1698.     
  1699.         0 if successful, otherwise an operating system error code
  1700.     
  1701.     
  1702.     DESCRIPTION:
  1703.     
  1704.           This function positions the operating system internal pointer into
  1705.        a file so that any read or write will take  place  at  the  specified
  1706.        position in the file.
  1707.     
  1708.           Most operating systems which support files of > 64K bytes in  size
  1709.        will support form (1) of the function, using both high and low offset
  1710.        values.
  1711.     
  1712.           Smaller operating  systems  may  only  support  form  (2)  of  the
  1713.        function, allowing seeking of only +/- 32K bytes.
  1714.     
  1715.           Also, some implementations may not support  all  "modes",  or  may
  1716.        only allow unsigned (positive) offsets.
  1717.     
  1718.           For use with LOW LEVEL (unbuffered I/O only).
  1719.     
  1720.     
  1721.     EXAMPLES:
  1722.     
  1723.         lseek(input_fh, 0, 2);  /* Advance to end of file */
  1724.     LTELL                                                             LTELL
  1725.     
  1726.     
  1727.     
  1728.     PROTOTYPE:
  1729.     
  1730.         (1) int ltell(HANDLE fh, int &h_offset, unsigned &l_offset)
  1731.         (2) int ltell(HANDLE fh, int &offset)
  1732.     
  1733.     
  1734.     ARGUMENTS:
  1735.     
  1736.         fh      - File handle of an open file
  1737.         h_offset- Address of int to receive high word of offset
  1738.         l_offset- Address of int to receive low word of offset
  1739.         offset  - Address of int to receive offset
  1740.     
  1741.     
  1742.     RETURN VALUE:
  1743.     
  1744.         0 if successful, otherwise an operating system error code
  1745.     
  1746.     
  1747.     DESCRIPTION:
  1748.     
  1749.           This function gets the current read/write position within a  file.
  1750.        The position returned indicates the absolute character (byte)  offset
  1751.        from the start of the file where the next read  or  write  will  take
  1752.        place.
  1753.     
  1754.           Most operating systems which support files of > 64K bytes in  size
  1755.        will support form (1) of the function, returning both  high  and  low
  1756.        offset values.
  1757.     
  1758.           Smaller operating  systems  may  only  support  form  (2)  of  the
  1759.        function,  allowing  access  to  only  the  first   65535   character
  1760.        positions.
  1761.     
  1762.           For use with LOW LEVEL (unbuffered I/O only).
  1763.     
  1764.     
  1765.     EXAMPLES:
  1766.     
  1767.         ltell(fp, &oldh, &oldl);    /* Save file position */
  1768.             . . .                   /* Perform some operations on the file */
  1769.         lseek(fp, oldh, oldl, 0);   /* Return to previous position */
  1770.     MALLOC                                                           MALLOC
  1771.     
  1772.     
  1773.     
  1774.     PROTOTYPE:
  1775.     
  1776.         char *malloc(int size)
  1777.     
  1778.     
  1779.     ARGUMENTS:
  1780.     
  1781.         size    - Size of memory block to allocate (in bytes).
  1782.     
  1783.     
  1784.     RETURN VALUE:
  1785.     
  1786.         0       - Memory allocation failed
  1787.         !0      - Pointer to allocated memory block
  1788.     
  1789.     
  1790.     DESCRIPTION:
  1791.     
  1792.           The "malloc" function allocates a block of memory of the specified
  1793.        size from the heap, and returns a pointer to  it.  This  memory  will
  1794.        remain allocated until it is  explicitly  releases  with  the  "free"
  1795.        function.
  1796.     
  1797.     
  1798.     EXAMPLES:
  1799.     
  1800.         if(!(ptr = malloc(BUFSIZ)))     /* Allocate a temporary buffer */
  1801.             abort("Not enough memory");
  1802.         do {                            /* Copy the file over */
  1803.             size = fread(ptr, BUFSIZ, in_fp);
  1804.             fwrite(ptr, size, out_fp); }
  1805.         while(size == BUFSIZ);
  1806.         free(ptr);                      /* Release temporary buffer */
  1807.     MAX                                                                 MAX
  1808.     
  1809.     
  1810.     
  1811.     PROTOTYPE:
  1812.     
  1813.         int max(int value1, int value2)
  1814.     
  1815.     
  1816.     ARGUMENTS:
  1817.     
  1818.         value1  - Any integer value
  1819.         value2  - Any integer value
  1820.     
  1821.     
  1822.     RETURN VALUE:
  1823.     
  1824.         The greater of "value1" or "value2"
  1825.     
  1826.     
  1827.     DESCRIPTION:
  1828.     
  1829.           The "max" function returns the higher of its two argument values.
  1830.     
  1831.     
  1832.     EXAMPLES:
  1833.     
  1834.         biggest = max(a, b);
  1835.     MEMCPY                                                           MEMCPY
  1836.     
  1837.     
  1838.     
  1839.     PROTOTYPE:
  1840.     
  1841.         memcpy(char *dest, char *source, unsigned size)
  1842.     
  1843.     
  1844.     ARGUMENTS:
  1845.     
  1846.         dest    - Pointer to the destination
  1847.         source  - Pointer to the souce
  1848.         size    - Number of bytes to copy
  1849.     
  1850.     
  1851.     RETURN VALUE:
  1852.     
  1853.         None
  1854.     
  1855.     
  1856.     DESCRIPTION:
  1857.     
  1858.           The "memcpy" function will copy the specified number of bytes from
  1859.        the source to the destination.
  1860.     
  1861.     
  1862.     EXAMPLES:
  1863.     
  1864.         memcpy(buffer1, buffer2, 256);
  1865.     MEMSET                                                           MEMSET
  1866.     
  1867.     
  1868.     
  1869.     PROTOTYPE:
  1870.     
  1871.         memset(char *block, char value, unsigned size)
  1872.     
  1873.     
  1874.     ARGUMENTS:
  1875.     
  1876.         block   - Pointer to a block of memory
  1877.         value   - Value to initialize memory with
  1878.         size    - Number of bytes to initialize
  1879.     
  1880.     
  1881.     RETURN VALUE:
  1882.     
  1883.         None
  1884.     
  1885.     
  1886.     DESCRIPTION:
  1887.     
  1888.           Sets a block of memory  beginning  at  the  pointer  "block",  for
  1889.        "size" bytes to the byte value "value".
  1890.     
  1891.     
  1892.     EXAMPLES:
  1893.     
  1894.         memset(buffer, 0, 100);
  1895.     MIN                                                                 MIN
  1896.     
  1897.     
  1898.     
  1899.     PROTOTYPE:
  1900.     
  1901.         int min(int value1, int value2)
  1902.     
  1903.     
  1904.     ARGUMENTS:
  1905.     
  1906.         value1  - Any integer value
  1907.         value2  - Any integer value
  1908.     
  1909.     
  1910.     RETURN VALUE:
  1911.     
  1912.         The smaller of "value1" or "value2"
  1913.     
  1914.     
  1915.     DESCRIPTION:
  1916.     
  1917.           The "min" function returns the lower of its two argument values.
  1918.     
  1919.     
  1920.     EXAMPLES:
  1921.     
  1922.         least = min(a, b);
  1923.     MKDIR                                                             MKDIR
  1924.     
  1925.     
  1926.     
  1927.     PROTOTYPE:
  1928.     
  1929.         int mkdir(char *pathname)
  1930.     
  1931.     
  1932.     ARGUMENTS:
  1933.     
  1934.         pathname- Name of directory to create
  1935.     
  1936.     
  1937.     RETURN VALUE:
  1938.     
  1939.         0 if successful, otherwise an operating system error code
  1940.     
  1941.     
  1942.     DESCRIPTION:
  1943.     
  1944.           The "mkdir" function create a new directory on the disk under  the
  1945.        specified path name.
  1946.     
  1947.     
  1948.     EXAMPLES:
  1949.     
  1950.         mkdir("subdir");
  1951.     NARGS                                                             NARGS
  1952.     
  1953.     
  1954.     
  1955.     PROTOTYPE:
  1956.     
  1957.         int nargs()
  1958.     
  1959.     
  1960.     ARGUMENTS:
  1961.     
  1962.         None
  1963.     
  1964.     
  1965.     RETURN VALUE:
  1966.     
  1967.         The number of arguments passed to the calling function
  1968.     
  1969.     
  1970.     DESCRIPTION:
  1971.     
  1972.           Returns the number of arguments passed to a "register" function.
  1973.     
  1974.           NOTE: When  calling  a  "register"  function,  MICRO-C  loads  the
  1975.        accumulator with the number of arguments just prior  to  calling  the
  1976.        function. This "nargs" routine is  simply  a  null  definition  which
  1977.        returns with the same value in the accumulator as was there  when  it
  1978.        was called. Therefore "nargs" MUST BE  THE  FIRST  ARITHMETIC  ENTITY
  1979.        EVALUATED WITHIN  THE  REGISTER  FUNCTION  or  the  contents  of  the
  1980.        accumulator will be lost. Some examples of "register" definitions and
  1981.        the use of "nargs" may be found in the library source code.
  1982.     
  1983.     
  1984.     EXAMPLES:
  1985.     
  1986.         first_arg = nargs() * 2 + &arguments;
  1987.     OPEN                                                               OPEN
  1988.     
  1989.     
  1990.     
  1991.     PROTOTYPE:
  1992.     
  1993.         HANDLE open(char *filename, int options)
  1994.     
  1995.     
  1996.     ARGUMENTS:
  1997.     
  1998.         filename- Name of the file to open
  1999.         options - Open options (defined in file.h)
  2000.     
  2001.     
  2002.     RETURN VALUE:
  2003.     
  2004.         File handle for the open file
  2005.         Zero (0) if file could not be opened
  2006.     
  2007.     
  2008.     DESCRIPTION:
  2009.     
  2010.           This function  open  a  file  for  direct  access  via  LOW  LEVEL
  2011.        (unbuffered) I/O.
  2012.     
  2013.     
  2014.     EXAMPLES:
  2015.     
  2016.         if(fh = open("data.img", F_READ)) {
  2017.             read(data_buf, 100, fh);
  2018.             close(fh); }
  2019.         else
  2020.             abort("Unable to read data file");
  2021.     OUT                                                                 OUT
  2022.     
  2023.     
  2024.     
  2025.     PROTOTYPE:
  2026.     
  2027.         out(unsigned port, int value)
  2028.     
  2029.     
  2030.     ARGUMENTS:
  2031.     
  2032.         port    - I/O port address
  2033.         value   - Value to write to I/O port
  2034.     
  2035.     
  2036.     RETURN VALUE:
  2037.     
  2038.         None
  2039.     
  2040.     
  2041.     DESCRIPTION:
  2042.     
  2043.           The "out" function writes a byte (8 bit) value to an I/O port.
  2044.     
  2045.           The valid range of values for "port" depends on  the  I/O  address
  2046.        space of the processor.
  2047.     
  2048.           This function is not provided for processors which do not  support
  2049.        a separate I/O address space.
  2050.     
  2051.     
  2052.     EXAMPLES:
  2053.     
  2054.         out(0, 0);      /* Output 0 to I/O port 0 */
  2055.     OUTW                                                               OUTW
  2056.     
  2057.     
  2058.     
  2059.     PROTOTYPE:
  2060.     
  2061.         outw(unsigned port, int value)
  2062.     
  2063.     
  2064.     ARGUMENTS:
  2065.     
  2066.         port    - I/O port address
  2067.         value   - Value to write to I/O port
  2068.     
  2069.     
  2070.     RETURN VALUE:
  2071.     
  2072.         None
  2073.     
  2074.     
  2075.     DESCRIPTION:
  2076.     
  2077.           The "outw" function writes a word (16 bit) value to an I/O port.
  2078.     
  2079.           The valid range of values for "port" depends on  the  I/O  address
  2080.        space of the processor.
  2081.     
  2082.           This function is not provided for processors which do not  support
  2083.        a separate I/O address space.
  2084.     
  2085.     
  2086.     EXAMPLES:
  2087.     
  2088.         outw(0, 0);     /* Write 0 to I/O ports 0 and 1 */
  2089.     PEEK                                                               PEEK
  2090.     
  2091.     
  2092.     
  2093.     PROTOTYPE:
  2094.     
  2095.         (1) int peek(unsigned address)
  2096.         (2) int peek(unsigned h_addr, unsigned l_addr)
  2097.         (3) int peek(unsigned segment, unsigned offset)
  2098.     
  2099.     
  2100.     ARGUMENTS:
  2101.     
  2102.         segment - Memory segment
  2103.         offset  - Offset into segment
  2104.         h_addr  - High word of memory address
  2105.         l_addr  - Low word of memory address
  2106.         address - 16 bit memory address
  2107.     
  2108.     
  2109.     RETURN VALUE:
  2110.     
  2111.         The 8 bit value read from the given memory address
  2112.     
  2113.     
  2114.     DESCRIPTION:
  2115.     
  2116.           The "peek" function reads and returns a byte (8 bits) from  memory
  2117.        as an integer value between 0 and 255.
  2118.     
  2119.           Processors such as the 8080 or 6809 which address 64K of memory or
  2120.        less use form (1) of the function.
  2121.     
  2122.           Non-segmented processors addressing more  than  64K  such  as  the
  2123.        68000 use form (2) of the function.
  2124.     
  2125.           Processors employing a "segmented" architecture such as  the  8086
  2126.        use form (3) of the function.
  2127.     
  2128.     
  2129.     EXAMPLES:
  2130.     
  2131.         while(peek(0)); /* Wait for flag to clear */
  2132.     PEEKW                                                             PEEKW
  2133.     
  2134.     
  2135.     
  2136.     PROTOTYPE:
  2137.     
  2138.         (1) int peekw(unsigned address)
  2139.         (2) int peekw(unsigned h_addr, unsigned l_addr)
  2140.         (3) int peekw(unsigned segment, unsigned offset)
  2141.     
  2142.     
  2143.     ARGUMENTS:
  2144.     
  2145.         segment - Memory segment
  2146.         offset  - Offset into segment
  2147.         h_addr  - High word of memory address
  2148.         l_addr  - Low word of memory address
  2149.         address - 16 bit memory address
  2150.     
  2151.     
  2152.     RETURN VALUE:
  2153.     
  2154.         The 16 bit value read from the given memory address
  2155.     
  2156.     
  2157.     DESCRIPTION:
  2158.     
  2159.           The "peekw" function reads and  returns  a  word  (16  bits)  from
  2160.        memory as an integer value between 0 and 65535 (-1).
  2161.     
  2162.           Processors such as the 8080 or 6809 which address 64K of memory or
  2163.        less use form (1) of the function.
  2164.     
  2165.           Non-segmented processors addressing more  than  64K  such  as  the
  2166.        68000 use form (2) of the function.
  2167.     
  2168.           Processors employing a "segmented" architecture such as  the  8086
  2169.        use form (3) of the function.
  2170.     
  2171.     
  2172.     EXAMPLES:
  2173.     
  2174.         var = peekw(0));
  2175.     POKE                                                               POKE
  2176.     
  2177.     
  2178.     
  2179.     PROTOTYPE:
  2180.     
  2181.         (1) poke(unsigned address, int value)
  2182.         (2) poke(unsigned h_addr, unsigned l_addr, int value)
  2183.         (3) poke(unsigned segment, unsigned offset, int value)
  2184.     
  2185.     
  2186.     ARGUMENTS:
  2187.     
  2188.         segment - Memory segment
  2189.         offset  - Offset into segment
  2190.         h_addr  - High word of memory address
  2191.         l_addr  - Low word of memory address
  2192.         address - 16 bit memory address
  2193.         value   - Value to be written to memory
  2194.     
  2195.     
  2196.     RETURN VALUE:
  2197.     
  2198.         None
  2199.     
  2200.     
  2201.     DESCRIPTION:
  2202.     
  2203.           The "poke" function writes a byte (8 bit) value to memory.
  2204.     
  2205.           Processors such as the 8080 or 6809 which address 64K of memory or
  2206.        less use form (1) of the function.
  2207.     
  2208.           Non-segmented processors addressing more  than  64K  such  as  the
  2209.        68000 use form (2) of the function.
  2210.     
  2211.           Processors employing a "segmented" architecture such as  the  8086
  2212.        use form (3) of the function.
  2213.     
  2214.     
  2215.     EXAMPLES:
  2216.     
  2217.         poke(0, 0);     /* Write 0 to location 0 */
  2218.     POKEW                                                             POKEW
  2219.     
  2220.     
  2221.     
  2222.     PROTOTYPE:
  2223.     
  2224.         (1) pokew(unsigned address, int value)
  2225.         (2) pokew(unsigned h_addr, unsigned l_addr, int value)
  2226.         (3) pokew(unsigned segment, unsigned offset, int value)
  2227.     
  2228.     
  2229.     ARGUMENTS:
  2230.     
  2231.         segment - Memory segment
  2232.         offset  - Offset into segment
  2233.         h_addr  - High word of memory address
  2234.         l_addr  - Low word of memory address
  2235.         address - 16 bit memory address
  2236.         value   - Value to be written to memory
  2237.     
  2238.     
  2239.     RETURN VALUE:
  2240.     
  2241.         None
  2242.     
  2243.     
  2244.     DESCRIPTION:
  2245.     
  2246.           The "pokew" function writes a word (16 bit) value to memory.
  2247.     
  2248.           Processors such as the 8080 or 6809 which address 64K of memory or
  2249.        less use form (1) of the function.
  2250.     
  2251.           Non-segmented processors addressing more  than  64K  such  as  the
  2252.        68000 use form (2) of the function.
  2253.     
  2254.           Processors employing a "segmented" architecture such as  the  8086
  2255.        use form (3) of the function.
  2256.     
  2257.     
  2258.     EXAMPLES:
  2259.     
  2260.         pokew(0, 0);    /* Write 0 to locations 0 and 1 */
  2261.     PRINTF                                                           PRINTF
  2262.     
  2263.     
  2264.     
  2265.     PROTOTYPE:
  2266.     
  2267.         register printf(char *format, arg, ...)
  2268.     
  2269.     
  2270.     ARGUMENTS:
  2271.     
  2272.         format  - Pointer to format string
  2273.         arg     - Argument as determined by format string
  2274.         ...     - Additional arguments may be required
  2275.     
  2276.     
  2277.     RETURN VALUE:
  2278.     
  2279.         None
  2280.     
  2281.     
  2282.     DESCRIPTION:
  2283.     
  2284.           The "printf" routine performs a formatted print  to  the  standard
  2285.        output device  (usually  system  console).  The  "format"  string  is
  2286.        written  with  the  arguments  substituted  for  special  "conversion
  2287.        characters".
  2288.     
  2289.           See "fprintf" for more information on format strings.
  2290.     
  2291.           NOTE: This function uses a variable number of arguments, and  must
  2292.        be declared as "register" (See "stdio.h").
  2293.     
  2294.     
  2295.     EXAMPLES:
  2296.     
  2297.         printf("Hello world!!!\n");
  2298.         printf("File '%s', has %u lines\n", filename, num_lines);
  2299.     PUTC                                                               PUTC
  2300.     
  2301.     
  2302.     
  2303.     PROTOTYPE:
  2304.     
  2305.         putc(char c, FILE *fp)
  2306.     
  2307.     
  2308.     ARGUMENTS:
  2309.     
  2310.         c       - Any character value
  2311.         fp      - File pointer to an output file
  2312.     
  2313.     
  2314.     RETURN VALUE:
  2315.     
  2316.         0 if successful, otherwise an operating system error code
  2317.     
  2318.     
  2319.     DECRIPTION:
  2320.     
  2321.           This function writes the character 'c' to the  file  indicated  by
  2322.        the file pointer 'fp'.
  2323.     
  2324.     
  2325.     EXAMPLES:
  2326.     
  2327.         putc('*', fp);
  2328.         putc('\n', stderr);
  2329.     RAND                                                               RAND
  2330.     
  2331.     
  2332.     
  2333.     PROTOTYPE:
  2334.     
  2335.         unsigned rand(unsigned limit)
  2336.     
  2337.     
  2338.     ARGUMENTS:
  2339.     
  2340.         limit   - Maximum value to return
  2341.     
  2342.     
  2343.     RETURN VALUE:
  2344.     
  2345.         A pseudo-random number in the range of 0 to (limit-1)
  2346.     
  2347.     
  2348.     DESCRIPTION:
  2349.     
  2350.           The "rand" function calculates the next value of  a  pseudo-random
  2351.        sequence, based on a 16 bit unsigned "seed" value, which it maintains
  2352.        in the global variable "RAND_SEED". The new value is  stored  as  the
  2353.        new seed value, and is then divided  by  the  "limit"  parameter,  to
  2354.        obtain the remainder, which is returned. This  results  in  a  random
  2355.        number in the range of zero (0) to (limit - 1).
  2356.     
  2357.           Any  particular  sequence  may  be  repeated,  by   reseting   the
  2358.        "RAND_SEED" value.
  2359.     
  2360.     
  2361.     EXAMPLES:
  2362.     
  2363.         value = rand(52);
  2364.     READ                                                               READ
  2365.     
  2366.     
  2367.     
  2368.     PROTOTYPE:
  2369.     
  2370.         int read(char *buffer, int size, HANDLE fh)
  2371.     
  2372.     
  2373.     ARGUMENTS:
  2374.     
  2375.         buffer  - Pointer to buffer to receive data
  2376.         size    - Number of bytes to read
  2377.         fh      - File handle of an input file
  2378.     
  2379.     
  2380.     RETURN VALUE:
  2381.     
  2382.         Number of bytes read from file
  2383.     
  2384.     
  2385.     DESCRIPTION:
  2386.     
  2387.           This function reads a block of data from a file  using  LOW  LEVEL
  2388.        (unbuffered) I/O, and places it in memory at the address of "buffer".
  2389.        Data is read in "raw"  form,  with  no  interpretation  of  "newline"
  2390.        characters etc. If the number of bytes  returned  is  less  than  the
  2391.        number of bytes requested, either the end of the file was encountered
  2392.        or an error condition occured (in which case the value will be zero).
  2393.     
  2394.     
  2395.     EXAMPLES:
  2396.     
  2397.         read(block, 512, input_fh);
  2398.     RENAME                                                           RENAME
  2399.     
  2400.     
  2401.     
  2402.     PROTOTYPE:
  2403.     
  2404.         int rename(char *pathname, char *newname)
  2405.     
  2406.     
  2407.     ARGUMENTS:
  2408.     
  2409.         pathname- Name of file to rename
  2410.         newname - New name for file
  2411.     
  2412.     
  2413.     RETURN VALUE:
  2414.     
  2415.         0 if successful, otherwise an operating system error code
  2416.     
  2417.     
  2418.     DESCRIPTION:
  2419.     
  2420.           This function changes the name of an existing file  to  the  ASCII
  2421.        string specified by newname.
  2422.     
  2423.     
  2424.     EXAMPLES:
  2425.     
  2426.         rename("output.dat", "output.bak");
  2427.     REWIND                                                           REWIND
  2428.     
  2429.     
  2430.     
  2431.     PROTOTYPE:
  2432.     
  2433.         int rewind(FILE *fp)
  2434.     
  2435.     
  2436.     ARGUMENTS:
  2437.     
  2438.         fp      - File pointer to an open file
  2439.     
  2440.     
  2441.     RETURN VALUE:
  2442.     
  2443.         0 if successful, otherwise an operating system error code
  2444.     
  2445.     
  2446.     DESCRIPTION:
  2447.     
  2448.           This function resets the operating system internal file pointer so
  2449.        than any subsequent read or writes will be at the  beginning  of  the
  2450.        file.
  2451.     
  2452.     
  2453.     EXAMPLES:
  2454.     
  2455.         rewind(input_file);
  2456.     RMDIR                                                             RMDIR
  2457.     
  2458.     
  2459.     
  2460.     PROTOTYPE:
  2461.     
  2462.         int rmdir(char *pathname)
  2463.     
  2464.     
  2465.     ARGUMENTS:
  2466.     
  2467.         pathname- Name of directory to delete
  2468.     
  2469.     
  2470.     RETURN VALUE:
  2471.     
  2472.         0 if successful, otherwise an operating system error code
  2473.     
  2474.     
  2475.     DESCRIPTION:
  2476.     
  2477.           This function removes a directory from the disk. On most  systems,
  2478.        the directory  must  be  empty  (contains  no  files)  otherwise  the
  2479.        function will fail.
  2480.     
  2481.     
  2482.     EXAMPLES:
  2483.     
  2484.         rmdir("subdir");
  2485.     SCANF                                                             SCANF
  2486.     
  2487.     
  2488.     
  2489.     PROTOTYPE:
  2490.     
  2491.         register int scanf(char *format, arg1, arg2, ...)
  2492.     
  2493.     
  2494.     ARGUMENTS:
  2495.     
  2496.         format  - Pointer to format string
  2497.         arg     - Argument as determined by format string
  2498.         ...     - Additional arguments may be required
  2499.     
  2500.     
  2501.     RETURN VALUE:
  2502.     
  2503.         The number of successful matches
  2504.         EOF (-1) if end of file or an error condition occurs
  2505.     
  2506.     
  2507.     DESCRIPTION:
  2508.     
  2509.           The "scanf" function reads and scans  a  line  from  the  standard
  2510.        input device (usually system console) for specific values. Values are
  2511.        read and assigned to  the  passed  argument  addresses  according  to
  2512.        special "conversion characters" in the "format" string.
  2513.     
  2514.           See "fscanf" for more information on format strings.
  2515.     
  2516.           NOTE: This function uses a variable number of arguments, and  must
  2517.        be declared as "register".
  2518.     
  2519.     
  2520.     EXAMPLES:
  2521.     
  2522.         do
  2523.             printf("Please enter your First & Last names, and your age?");
  2524.         while(scanf("%s %s %u", first_name, last_name, &age) != 3);
  2525.     SETBUF                                                           SETBUF
  2526.     
  2527.     
  2528.     
  2529.     PROTOTYPE:
  2530.     
  2531.         FILE *setbuf(FILE *fp, int size)
  2532.     
  2533.     
  2534.     ARGUMENTS:
  2535.     
  2536.         fp      - File pointer to an open file
  2537.         size    - Size of new I/O buffer
  2538.     
  2539.     
  2540.     RETURN VALUE:
  2541.     
  2542.         If successful, a new file pointer is returned, and the old one
  2543.         is released. On failure the old file pointer is returned.
  2544.     
  2545.     
  2546.     DESCRIPTION:
  2547.     
  2548.           The "setbuf" function will adjust the size of the buffer used  for
  2549.        I/O operations on the indicated open file.
  2550.     
  2551.           This is the ONLY way to set the buffer size for  the  "stdin"  and
  2552.        "stdout" streams. If you change the size of the "stdout" buffer,  you
  2553.        must remember to "fflush(stdout)" before terminating,  otherwise  the
  2554.        last buffer contents may not be written.
  2555.     
  2556.           For file opened by "fopen",  the  buffer  size  may  be  set  more
  2557.        efficently by setting the value of the external  variable  "IOB_size"
  2558.        prior to calling "fopen".
  2559.     
  2560.           If "setbuf" is unable to allocate space for  the  new  buffer,  it
  2561.        will return the old file pointer unchanged.
  2562.     
  2563.     
  2564.     EXAMPLES:
  2565.     
  2566.         stdout = setbuf(stdout, 512);   /* Set stdout to 512 byte buffer */
  2567.     SETJMP                                                           SETJMP
  2568.     
  2569.     
  2570.     
  2571.     PROTOTYPE:
  2572.     
  2573.         int setjmp(int savenv[3])
  2574.     
  2575.     
  2576.     ARGUMENTS:
  2577.     
  2578.         savenv  - Save area for program context
  2579.     
  2580.     
  2581.     RETURN VALUE:
  2582.     
  2583.         0 is returned when actually called
  2584.         Value passed to "longjmp" is returned otherwise
  2585.     
  2586.     
  2587.     DESCRIPTION:
  2588.     
  2589.           When called, the "setjmp" function stores  the  current  execution
  2590.        state of the program into the passed integer array, and  returns  the
  2591.        value zero.
  2592.     
  2593.           The "longjmp" function may then be used to return the  program  to
  2594.        the "setjmp" call. In this case, the value returned by "setjmp"  will
  2595.        be the value which was passed to "longjmp". This allows the  function
  2596.        containing "setjmp" to determine which call to  "longjmp"  transfered
  2597.        execution to it.
  2598.     
  2599.           See also LONGJMP.
  2600.     
  2601.     
  2602.     EXAMPLES:
  2603.     
  2604.         switch(setjmp(savearea)) {
  2605.             case 0 : printf("Longjmp has been set up"); break;
  2606.             case 1 : printf("Control-C Interrupt");     break;
  2607.             case 2 : printf("Reset command executed");  break;
  2608.             default: printf("Software error trap");     break; }
  2609.     SPRINTF                                                         SPRINTF
  2610.     
  2611.     
  2612.     
  2613.     PROTOTYPE:
  2614.     
  2615.         register sprintf(char *dest, char *format, arg, ...)
  2616.     
  2617.     
  2618.     ARGUMENTS:
  2619.     
  2620.         dest    - Pointer to destination string
  2621.         format  - Pointer to format string
  2622.         arg     - Argument as determined by format string
  2623.         ...     - Additional arguments may be required
  2624.     
  2625.     
  2626.     RETURN VALUE:
  2627.     
  2628.         None
  2629.     
  2630.     
  2631.     DESCRIPTION:
  2632.     
  2633.           The "sprintf" routine performs a formatted print to  a  string  in
  2634.        memory. The "format" string is written to the destination string with
  2635.        the arguments substituted for special "conversion characters".
  2636.     
  2637.           See "fprintf" for more information on format strings.
  2638.     
  2639.           NOTE: This function uses a variable number of arguments, and  must
  2640.        be declared as "register" (See "stdio.h").
  2641.     
  2642.     
  2643.     EXAMPLES:
  2644.     
  2645.         sprintf(header_file, "/lib/%s.h", header_name);
  2646.     SQRT                                                               SQRT
  2647.     
  2648.     
  2649.     
  2650.     PROTOTYPE:
  2651.     
  2652.         int sqrt(unsigned value)
  2653.     
  2654.     
  2655.     ARGUMENTS:
  2656.     
  2657.         value   - Number for which to calculate square root
  2658.     
  2659.     
  2660.     RETURN VALUE:
  2661.     
  2662.         The integer square root (rounded up) of the argument value
  2663.     
  2664.     
  2665.     DESCRIPTION:
  2666.     
  2667.           The  SQRT  function  returns  the  smallest  number   which   when
  2668.        multiplied by itself will give a number equal to or larger  that  the
  2669.        argument value.
  2670.     
  2671.     
  2672.     EXAMPLES:
  2673.     
  2674.     /*
  2675.      * Draw a circle about point (x, y) of radus (r)
  2676.      */
  2677.     circle(x, y, r)
  2678.         int x, y, r;
  2679.     {
  2680.         int i, j, k, rs, lj;
  2681.     
  2682.         rs = (lj = r)*r;
  2683.         for(i=0; i <= r; ++i) {
  2684.             j = k = sqrt(rs - (i*i));
  2685.             do {
  2686.                 plot_xy(x+i, y+j);
  2687.                 plot_xy(x+i, y-j);
  2688.                 plot_xy(x-i, y+j);
  2689.                 plot_xy(x-i, y-j); }
  2690.             while(++j < lj);
  2691.             lj = k; }
  2692.     }
  2693.     SSCANF                                                           SSCANF
  2694.     
  2695.     
  2696.     
  2697.     PROTOTYPE:
  2698.     
  2699.         register int sscanf(char *input, char *format, arg1, arg2, ...)
  2700.     
  2701.     
  2702.     ARGUMENTS:
  2703.     
  2704.         input   - Pointer to input string
  2705.         format  - Pointer to format string
  2706.         arg     - Argument as determined by format string
  2707.         ...     - Additional arguments may be required
  2708.     
  2709.     
  2710.     RETURN VALUE:
  2711.     
  2712.         The number of successful matches
  2713.     
  2714.     
  2715.     DESCRIPTION:
  2716.     
  2717.           The "sscanf" function  scans  a  string  in  memory  for  specific
  2718.        values. Values are read and assigned to the passed argument addresses
  2719.        according to special "conversion characters" in the "format" string.
  2720.     
  2721.           See "fscanf" for more information on format strings.
  2722.     
  2723.           NOTE: This function uses a variable number of arguments, and  must
  2724.        be declared as "register".
  2725.     
  2726.     
  2727.     EXAMPLES:
  2728.     
  2729.         sscanf(pathname,"/%s/%s", directory, filename);
  2730.     STRBEG                                                           STRBEG
  2731.     
  2732.     
  2733.     
  2734.     PROTOTYPE:
  2735.     
  2736.         int strbeg(char *string1, char *string2)
  2737.     
  2738.     
  2739.     ARGUMENTS:
  2740.     
  2741.         string1 - Pointer to character string to test
  2742.         string2 - Pointer to character string to check for
  2743.     
  2744.     
  2745.     RETURN VALUE:
  2746.     
  2747.         0   - String1 does not begin with string2
  2748.         1   - String1 begins with string2
  2749.     
  2750.     
  2751.     DECRIPTION:
  2752.     
  2753.           Tests the passed "string1" to determine if it begins with the same
  2754.        data as is contained within "string2".
  2755.     
  2756.     
  2757.     EXAMPLES:
  2758.     
  2759.         if(strbeg(command, "delete"))
  2760.             delete_file(&command[6]);
  2761.     STRCAT                                                           STRCAT
  2762.     
  2763.     
  2764.     
  2765.     PROTOTYPE:
  2766.     
  2767.         char *strcat(char *dest, *source)
  2768.     
  2769.     
  2770.     ARGUMENTS:
  2771.     
  2772.         dest    - Pointer to destination string
  2773.         source  - Pointer to source string
  2774.     
  2775.     
  2776.     RETURN VALUE:
  2777.     
  2778.         Pointer to zero terminating destination string
  2779.     
  2780.     
  2781.     DESCRIPTION:
  2782.     
  2783.           This function concatinates the source string onto the tail of  the
  2784.        destination string. The destination string must be  large  enough  to
  2785.        hold the entire contents of both strings.
  2786.     
  2787.     
  2788.     EXAMPLES:
  2789.     
  2790.         strcat(program_name, ".c");
  2791.     STRCHR                                                           STRCHR
  2792.     
  2793.     
  2794.     
  2795.     PROTOTYPE:
  2796.     
  2797.         char *strchr(char *string, char chr)
  2798.     
  2799.     
  2800.     ARGUMENTS:
  2801.     
  2802.         string  - Pointer to a character string
  2803.         chr     - Character to look for
  2804.     
  2805.     
  2806.     RETURN VALUE:
  2807.     
  2808.         Pointer to the first occurance of 'chr' in 'string'
  2809.         Zero (0) if character was not found
  2810.     
  2811.     
  2812.     DECRIPTION:
  2813.     
  2814.           Searches  the  passed  string  got  the  first  occurance  of  the
  2815.        specified character. If the character is  found,  a  pointer  to  its
  2816.        position in the string is returned. If the character is not found,  a
  2817.        null pointer is returned.
  2818.     
  2819.           The null (0) character is treated as valid data by this  function,
  2820.        thus:
  2821.           strchr(string, 0);
  2822.     
  2823.        would return the position of the null terminator of the string.
  2824.     
  2825.     
  2826.     EXAMPLES:
  2827.     
  2828.         comma = strchr(buffer, ',');
  2829.     STRCMP                                                           STRCMP
  2830.     
  2831.     
  2832.     
  2833.     PROTOTYPE:
  2834.     
  2835.         int strcmp(char *string1, char *string2)
  2836.     
  2837.     
  2838.     ARGUMENTS:
  2839.     
  2840.         string1 - Pointer to first string
  2841.         string2 - Pointer to second string
  2842.     
  2843.     
  2844.     RETURN VALUE:
  2845.     
  2846.         0   - Strings match exactly
  2847.         1   - String1 is greater than string2
  2848.         -1  - String2 is greater than string1
  2849.     
  2850.     
  2851.     DESCRIPTION:
  2852.     
  2853.           This function compares two strings character by character. If  the
  2854.        two strings are identical, a zero  (0)  is  returned.  If  the  first
  2855.        string is greater than the second (as far as ASCII is  concerned),  a
  2856.        one (1) is returned. If the second string is greater, a negative  one
  2857.        (-1) is returned.
  2858.     
  2859.     
  2860.     EXAMPLES:
  2861.     
  2862.         if(!strcmp(command, "quit"))
  2863.             exit(0);
  2864.     STRCPY                                                           STRCPY
  2865.     
  2866.     
  2867.     
  2868.     PROTOTYPE:
  2869.     
  2870.         char *strcpy(char *dest, char *source)
  2871.     
  2872.     
  2873.     ARGUMENTS:
  2874.     
  2875.         dest    - Pointer to destination string
  2876.         souce   - Pointer to source string
  2877.     
  2878.     
  2879.     RETURN VALUE:
  2880.     
  2881.         Pointer to zero terminating destination string
  2882.     
  2883.     
  2884.     DESCRIPTION:
  2885.     
  2886.           This function copies the source string to the destination  string.
  2887.        All data is copied up to and including the zero byte which terminates
  2888.        the string. The destination string must be large enough to  hold  the
  2889.        entire source.
  2890.     
  2891.     
  2892.     EXAMPLES:
  2893.     
  2894.         strcpy(filename, argv[1]);
  2895.     STRLEN                                                           STRLEN
  2896.     
  2897.     
  2898.     
  2899.     PROTOTYPE:
  2900.     
  2901.         int strlen(char *string)
  2902.     
  2903.     
  2904.     ARGUMENTS:
  2905.     
  2906.         string  - Pointer to a character string
  2907.     
  2908.     
  2909.     RETURN VALUE:
  2910.     
  2911.         The length of the string
  2912.     
  2913.     
  2914.     DECRIPTION:
  2915.     
  2916.           Returns the length in character of the passed string.  The  length
  2917.        does not include the zero byte which terminates the string.
  2918.     
  2919.     
  2920.     EXAMPLES:
  2921.     
  2922.         length = strlen(command);
  2923.     STRNCAT                                                         STRNCAT
  2924.     
  2925.     
  2926.     
  2927.     PROTOTYPE:
  2928.     
  2929.         char *strncat(char *dest, *source, unsigned length)
  2930.     
  2931.     
  2932.     ARGUMENTS:
  2933.     
  2934.         dest    - Pointer to destination string
  2935.         source  - Pointer to source string
  2936.         length  - Maximum number of characters to copy
  2937.     
  2938.     
  2939.     RETURN VALUE:
  2940.     
  2941.         Pointer to zero terminating destination string
  2942.     
  2943.     
  2944.     DESCRIPTION:
  2945.     
  2946.           This function concatinates the source string onto the tail of  the
  2947.        destination string. If the source string exceeds  "length"  bytes  in
  2948.        size, only that many characters are copied.
  2949.     
  2950.     
  2951.     EXAMPLES:
  2952.     
  2953.         strncat(path, filename, 64);
  2954.     STRNCMP                                                         STRNCMP
  2955.     
  2956.     
  2957.     
  2958.     PROTOTYPE:
  2959.     
  2960.         int strncmp(char *string1, char *string2, unsigned length)
  2961.     
  2962.     
  2963.     ARGUMENTS:
  2964.     
  2965.         string1 - Pointer to first string
  2966.         string2 - Pointer to second string
  2967.         length  - Number of bytes to compare
  2968.     
  2969.     
  2970.     RETURN VALUE:
  2971.     
  2972.         0   - Strings match exactly
  2973.         1   - String1 is greater than string2
  2974.         -1  - String2 is greater than string1
  2975.     
  2976.     
  2977.     DESCRIPTION:
  2978.     
  2979.           This function compares two strings character  by  character  until
  2980.        either a difference is detected, or  "length"  characters  have  been
  2981.        compared. If the two string portions are identical,  a  zero  (0)  is
  2982.        returned. If the first string is greater than the second (as  far  as
  2983.        ASCII is concerned), a one (1) is returned. If the second  string  is
  2984.        greater, a negative one (-1) is returned.
  2985.     
  2986.     
  2987.     EXAMPLES:
  2988.     
  2989.         len = strlen(buffer) - 3;
  2990.         for(i=1; i < len; ++i)
  2991.             if(strncmp(&buffer[i], "***", 3)
  2992.                 abort("Found three stars\n");
  2993.     STRNCPY                                                         STRNCPY
  2994.     
  2995.     
  2996.     
  2997.     PROTOTYPE:
  2998.     
  2999.         strncpy(char *dest, char *source, unsigned length)
  3000.     
  3001.     
  3002.     ARGUMENTS:
  3003.     
  3004.         dest    - Pointer to destination string
  3005.         souce   - Pointer to source string
  3006.         length  - Number of bytes to copy
  3007.     
  3008.     
  3009.     RETURN VALUE:
  3010.     
  3011.         None
  3012.     
  3013.     
  3014.     DESCRIPTION:
  3015.     
  3016.           This function copies "length" characters from the source string to
  3017.        the  destination  string.  If  the  source  string  is  shorter  than
  3018.        "length", the destination string is padded with nulls. If the  source
  3019.        string is longer than "length", only that many characters are copied,
  3020.        and the destination string is NOT zero terminated.
  3021.     
  3022.     
  3023.     EXAMPLES:
  3024.     
  3025.         strncpy(filename, argv[1], 64);
  3026.     STRSTR                                                           STRSTR
  3027.     
  3028.     
  3029.     
  3030.     PROTOTYPE:
  3031.     
  3032.         char *strstr(char *string1, char *string2)
  3033.     
  3034.     
  3035.     ARGUMENTS:
  3036.     
  3037.         string1 - Pointer to character string to test
  3038.         string2 - Pointer to substring to search for
  3039.     
  3040.     
  3041.     RETURN VALUE:
  3042.     
  3043.         Pointer to substring, or 0 if not found
  3044.     
  3045.     
  3046.     DECRIPTION:
  3047.     
  3048.           Searches the passed "string1"  for  the  first  occurance  of  the
  3049.        passed "string2". If found,  a  pointer  to  the  beginning  of  that
  3050.        substring within "string1" is returned.
  3051.     
  3052.     
  3053.     EXAMPLES:
  3054.     
  3055.         if(ptr = strstr(command, "delete"))
  3056.             delete_file(&ptr[6]);
  3057.     SYSTEM                                                           SYSTEM
  3058.     
  3059.     
  3060.     
  3061.     PROTOTYPE:
  3062.     
  3063.         int system(char *command)
  3064.     
  3065.     
  3066.     ARGUMENTS:
  3067.     
  3068.         command - A system command to be executed
  3069.     
  3070.     
  3071.     RETURN VALUE:
  3072.     
  3073.         0 if successful, otherwise an operating system error code
  3074.     
  3075.     
  3076.     DESCRIPTION:
  3077.     
  3078.           The SYSTEM function accepts any  operating  system  command  as  a
  3079.        string parameter, and passes that command to the operating system  to
  3080.        be executed.
  3081.     
  3082.           When the command has terminated,  execution  will  resume  in  the
  3083.        MICRO-C program, with the statement following the call to SYSTEM.
  3084.     
  3085.     
  3086.     EXAMPLES:
  3087.     
  3088.         system("DEL *.TMP");
  3089.     TOLOWER                                                         TOLOWER
  3090.     
  3091.     
  3092.     
  3093.     PROTOTYPE:
  3094.     
  3095.         char tolower(char c)
  3096.     
  3097.     
  3098.     ARGUMENTS:
  3099.     
  3100.         c   - Any character value
  3101.     
  3102.     
  3103.     RETURN VALUE:
  3104.     
  3105.         The value of 'c', converted to lower case
  3106.     
  3107.     
  3108.     DESCRIPTION:
  3109.     
  3110.           Returns the value of 'c' converted to lower case. If 'c' is not  a
  3111.        letter of upper case, no change is made, and the  original  value  of
  3112.        'c' is returned.
  3113.     
  3114.     
  3115.     EXAMPLES:
  3116.     
  3117.         input_char = tolower(getc(stdin));
  3118.     TOUPPER                                                         TOUPPER
  3119.     
  3120.     
  3121.     
  3122.     PROTOTYPE:
  3123.     
  3124.         char toupper(char c)
  3125.     
  3126.     
  3127.     ARGUMENTS:
  3128.     
  3129.         c   - Any character value
  3130.     
  3131.     
  3132.     RETURN VALUE:
  3133.     
  3134.         The value of 'c', converted to upper case
  3135.     
  3136.     
  3137.     DESCRIPTION:
  3138.     
  3139.           Returns the value of 'c' converted to upper case. If 'c' is not  a
  3140.        letter of lower case, no change is made, and the  original  value  of
  3141.        'c' is returned.
  3142.     
  3143.     
  3144.     EXAMPLES:
  3145.     
  3146.         putc(toupper(output_char), stdout);
  3147.     WRITE                                                             WRITE
  3148.     
  3149.     
  3150.     
  3151.     PROTOTYPE:
  3152.     
  3153.         int write(char *block, int size, HANDLE fh)
  3154.     
  3155.     
  3156.     ARGUMENTS:
  3157.     
  3158.         block   - Pointer to a block of data to write
  3159.         size    - Number of bytes to write
  3160.         fh      - File handle of an output file
  3161.     
  3162.     
  3163.     RETURN VALUE:
  3164.     
  3165.         0 if successful, otherwise an operating system error code
  3166.     
  3167.     
  3168.     DESCRIPTION:
  3169.     
  3170.           This function writes a block of data to the indicated  file  using
  3171.        low level (unbuffered) I/O from memory at the specified address. Data
  3172.        is  written  in  "raw"  form,  with  no  translations  of   "newline"
  3173.        characters etc. If the value returned is less than the value  of  the
  3174.        "size" parameter, some error condition  has  occured  (Such  as  disk
  3175.        full).
  3176.     
  3177.     
  3178.     EXAMPLES:
  3179.     
  3180.         if(write(buffer, 100, fh) < 100)
  3181.             abort("File write error\n");
  3182.     MICRO-C Library                                                  Page: 3
  3183.  
  3184.  
  3185.     
  3186.                       +---------------------------------+
  3187.                       |                                 |
  3188.                       |  *****************************  |
  3189.                       |  * The IBM-PC/MS-DOS library *  |
  3190.                       |  *****************************  |
  3191.                       |                                 |
  3192.                       +---------------------------------+
  3193.     
  3194.     
  3195.     
  3196.     
  3197.     
  3198.     
  3199.     
  3200.     
  3201.     
  3202.     
  3203.        1.2 IBM-PC/MS-DOS Library
  3204.     
  3205.              The library functions described  on  the  following  pages  are
  3206.           available only under the MS-DOS operating  system,  on  IBM-PC  or
  3207.           compatible systems.
  3208.     
  3209.              These routines perform operations which are closely tied to the
  3210.           8086 family of processors, the  IBM-PC  hardware,  or  the  MS-DOS
  3211.           operating system, and are therefore impractical to implement on  a
  3212.           "general" basis.
  3213.     ALLOCA                                                           ALLOCA
  3214.     
  3215.     
  3216.     
  3217.     PROTOTYPE:
  3218.     
  3219.         char *alloca(int size)
  3220.     
  3221.     
  3222.     ARGUMENTS:
  3223.     
  3224.         size    - Size of memory block to allocate (in bytes).
  3225.     
  3226.     
  3227.     RETURN VALUE:
  3228.     
  3229.         0       - Memory allocation failed
  3230.         !0      - Pointer to allocated memory
  3231.     
  3232.     
  3233.     DESCRIPTION:
  3234.     
  3235.           The "alloca" function  allocates  a  block  of  automatic  (stack)
  3236.        memory, which exists only only until the  function  calling  "alloca"
  3237.        returns. When that function returns, all stack memory  including  any
  3238.        allocated by "alloca" is released.
  3239.     
  3240.        NOTE: THE FOLLOWING RESTRICTIONS APPLY TO THE USE OF ALLOCA:
  3241.     
  3242.           The function calling 'alloca' MUST have  at  least  one  automatic
  3243.        (local) variable, otherwise MICRO-C will not  restore  the  stack  on
  3244.        exit.
  3245.     
  3246.           The 'alloca' function must be used within a simple expression,  at
  3247.        a point where there will be no partial results stored on the stack.
  3248.     
  3249.           The above conditions can best be met by declaring a local  pointer
  3250.        which will hold the memory address, and assigning it the value of the
  3251.        'alloca' call in a single statement. The address returned by 'alloca'
  3252.        should NOT be assigned to a calculated  address  (such  as  an  array
  3253.        element or indirect reference via a pointer), since this  may  result
  3254.        in stack activity.
  3255.     
  3256.           NOTE: The size operand to 'alloca' can be  a  complex  expression,
  3257.        since any stack operations it causes will have dissipated by the time
  3258.        'alloca' gets called.
  3259.     
  3260.     
  3261.     EXAMPLES:
  3262.     
  3263.     func(string)
  3264.         char *string;
  3265.     {
  3266.         char *local_memory;
  3267.     
  3268.         if(!(local_memory = alloca(strlen(string)+1)))
  3269.             abort("Not enough memory for alloca");
  3270.         /* ... */
  3271.     }
  3272.     ALLOC_SEG                                                     ALLOC_SEG
  3273.     
  3274.     
  3275.     
  3276.     PROTOTYPE:
  3277.     
  3278.         int alloc_seg(int size)
  3279.     
  3280.     
  3281.     ARGUMENTS:
  3282.     
  3283.         size    - Number of 16 byte paragraphs to allocate
  3284.     
  3285.     
  3286.     RETURN VALUE:
  3287.     
  3288.     
  3289.         0       - Not enough free memory available
  3290.         !0      - The segment address of the allocated memory
  3291.     
  3292.     
  3293.     DESCRIPTION:
  3294.     
  3295.           The "alloc_seg" function allocates a 'segment' of memory from DOS.
  3296.        The size is given in 16 byte "paragraphs". The allocated memory  will
  3297.        be outside of the data memory available to the MICRO-C  program,  and
  3298.        therefore must be accessed via assembly lenguage functions,  or  with
  3299.        the "peek" and "poke" library functions.
  3300.     
  3301.     
  3302.     EXAMPLES:
  3303.     
  3304.         if(!(aseg = alloc(4096)))   /* Get a 64K data segment */
  3305.             abort("Not enough memory!!!");
  3306.         set_es(aseg);               /* Set up extra segment */
  3307.         asm_func();                 /* Invoke assembler function */
  3308.     CCLOSE                                                           CCLOSE
  3309.     
  3310.     
  3311.     
  3312.     PROTOTYPE:
  3313.     
  3314.         Cclose()
  3315.     
  3316.     
  3317.     ARGUMENTS:
  3318.     
  3319.         None
  3320.     
  3321.     
  3322.     RETURN VALUE:
  3323.     
  3324.         None
  3325.     
  3326.     
  3327.     DESCRIPTION:
  3328.     
  3329.           This function closes the  communications  port  previously  opened
  3330.        using "Copen". The system interrupt vectors and all  other  hooks  to
  3331.        the comm port are restored.
  3332.     
  3333.           This function must be called  before  any  program  using  "Copen"
  3334.        terminates, otherwise the communications port  will  be  left  in  an
  3335.        indeterminate state. If this is not done, there will be a possibility
  3336.        of system crash if an interrupt is received from the port  after  the
  3337.        program has terminated.
  3338.     
  3339.     
  3340.     EXAMPLES:
  3341.     
  3342.         Cclose();       /* Close comm port */
  3343.         exit(0);        /* And terminate */
  3344.     CGETC                                                             CGETC
  3345.     
  3346.     
  3347.     
  3348.     PROTOTYPE:
  3349.     
  3350.         int Cgetc()
  3351.     
  3352.     
  3353.     ARGUMENTS:
  3354.     
  3355.         None
  3356.     
  3357.     
  3358.     RETURN VALUE:
  3359.     
  3360.         Character read from the communications port
  3361.     
  3362.     
  3363.     DESCRIPTION:
  3364.     
  3365.           This function reads a single  character  from  the  communications
  3366.        port previously opened with "Copen". If no  character  is  available,
  3367.        "Cgetc" will wait for one.
  3368.     
  3369.     
  3370.     EXAMPLES:
  3371.     
  3372.         /* Get a string from the comm port */
  3373.         while((c = cgetc()) != '\r')
  3374.             *ptr++ = c;
  3375.         *ptr = 0;
  3376.     COPEN                                                             COPEN
  3377.     
  3378.     
  3379.     
  3380.     PROTOTYPE:
  3381.     
  3382.         int Copen(int port, int speed, int mode, int modem)
  3383.     
  3384.     
  3385.     ARGUMENTS:
  3386.     
  3387.         port    - Comm port to use (1 or 2)
  3388.         speed   - Baudrate divisor to set
  3389.         mode    - Communications parameters to set
  3390.         modem   - Modem control lines to set
  3391.     
  3392.     RETURN VALUE:
  3393.     
  3394.         0       - Successful open
  3395.         !0      - Requested comm port is not available
  3396.     
  3397.     
  3398.     DESCRIPTION:
  3399.     
  3400.           The "Copen" function opens a serial communications port on the IBM
  3401.        PC for access. An independant interrupt handler and I/O  drivers  are
  3402.        installed, which allow high speed full duplex operation of the serial
  3403.        port with optional XON/XOFF flow control of both receive and transmit
  3404.        streams.
  3405.     
  3406.           Only one serial port  may  be  accessed  at  a  time  using  these
  3407.        functions, If "Copen" is called more than once, it will automatically
  3408.        close the last port before opening the new one.
  3409.     
  3410.           The meaning of the "speed",  "mode",  and  "modem"  parameters  if
  3411.        documented in the "comm.h" header file.
  3412.     
  3413.           An external "char" variable "Cflags" may be accessed to enable  or
  3414.        disable transparency of the serial  channel.  When  "transparent"  is
  3415.        selected, XON/XOFF flow control is disabled, and all data is sent and
  3416.        received with no changes. When  operating  in  this  mode,  you  must
  3417.        insure that "Cgetc" is called frequently enough  that  the  256  byte
  3418.        internal receive buffer will not overflow.
  3419.     
  3420.           Since "Cflags" is  used  by  the  interrupt  handler,  you  should
  3421.        disable and enable interrupts around any accesses to it.
  3422.     
  3423.     
  3424.     
  3425.     EXAMPLES:
  3426.     
  3427.         #include comm.h     /* Get comm port defintions */
  3428.     
  3429.             extern char Cflags;
  3430.     
  3431.         /*
  3432.          * Program to read & echo characters on the serial port
  3433.          * in transparent mode. (Until ESCAPE char is received)
  3434.          */
  3435.         main()
  3436.         {
  3437.             char c;
  3438.     
  3439.             if(Copen(1, _2400, PAR_NO|DATA_8|STOP_1, SET_RTS|SET_DTR))
  3440.                 abort("Cannot access COM1");
  3441.     
  3442.             disable();                  /* Disable interrupts */
  3443.             Cflags |= TRANSPARENT;      /* Set transparency */
  3444.             enable();                   /* Re-enable interrupts */
  3445.     
  3446.             while((c = Cgetc()) != 0x1B)    /* Do until ESCAPE */
  3447.                 Cputc(c);
  3448.     
  3449.             Cclose();                   /* Close the serial port */
  3450.         }
  3451.     COPY_SEG                                                       COPY_SEG
  3452.     
  3453.     
  3454.     
  3455.     PROTOTYPE:
  3456.     
  3457.         copy_seg(int dseg, int doffset, int sseg, int soffset, int size)
  3458.     
  3459.     
  3460.     ARGUMENTS:
  3461.     
  3462.         dseg    - Destination segment
  3463.         doffset - Destination offset
  3464.         sseg    - Source segment
  3465.         soffset - Source offset
  3466.         size    - Number of bytes to copy
  3467.     
  3468.     
  3469.     RETURN VALUE:
  3470.     
  3471.         None
  3472.     
  3473.     
  3474.     DESCRIPTION:
  3475.     
  3476.           This function  perform  a  copy  between  80X86  processor  memory
  3477.        segments. A number of bytes equal to "size" is copied from the source
  3478.        segment and offset to the destination segment and offset.
  3479.     
  3480.     
  3481.     EXAMPLES:
  3482.     
  3483.         /* Save the video display contents */
  3484.         copy_seg(get_ds(), buffer, _V_BASE, 0, (25*80)*2);
  3485.     CPU                                                                 CPU
  3486.     
  3487.     
  3488.     
  3489.     PROTOTYPE:
  3490.     
  3491.         int cpu()
  3492.     
  3493.     
  3494.     ARGUMENTS:
  3495.     
  3496.         None
  3497.     
  3498.     
  3499.     RETURN VALUE:
  3500.     
  3501.         0       - CPU is 8088 or 8086
  3502.         1       - CPU is 80188 or 80186
  3503.         2       - CPU is 80286
  3504.         3       - CPU is 80386 or 80486
  3505.     
  3506.     
  3507.     DESCRIPTION:
  3508.     
  3509.           This function  returns  a  simple  integer  which  identifies  the
  3510.        processor type on which the program is currently executing.
  3511.     
  3512.     
  3513.     EXAMPLES:
  3514.     
  3515.         if(cpu() < 2)
  3516.             abort("This program requires at least an 80286");
  3517.     CPUTC                                                             CPUTC
  3518.     
  3519.     
  3520.     
  3521.     PROTOTYPE:
  3522.     
  3523.         Cputc(char c)
  3524.     
  3525.     
  3526.     ARGUMENTS:
  3527.     
  3528.         c       - Character to write to communciation port
  3529.     
  3530.     
  3531.     RETURN VALUE:
  3532.     
  3533.         None
  3534.     
  3535.     
  3536.     DESCRIPTION:
  3537.     
  3538.           The  "Cputc"  function  writes  the   given   character   to   the
  3539.        communcinations port previously opened by "Copen".
  3540.     
  3541.     
  3542.     EXAMPLES:
  3543.     
  3544.         while(*ptr)         /* Write a string to comm port */
  3545.             Cputc(*ptr++);
  3546.     CSIGNALS                                                       CSIGNALS
  3547.     
  3548.     
  3549.     
  3550.     PROTOTYPE:
  3551.     
  3552.         int Csignals()
  3553.     
  3554.     
  3555.     ARGUMENTS:
  3556.     
  3557.         None
  3558.     
  3559.     
  3560.     RETURN VALUE:
  3561.     
  3562.         The modem input signals read from the open comm port
  3563.     
  3564.     
  3565.     DESCRIPTION:
  3566.     
  3567.           This function reads the modem input signals (DSR, CD, RI etc) from
  3568.        the serial communication  port  previously  opened  by  "Copen",  and
  3569.        returns them as an integer value.
  3570.     
  3571.           The meaning of the  individual  bits  in  the  value  returned  by
  3572.        "Csignals" is documented in the "comm.h" header file.
  3573.     
  3574.     
  3575.     EXAMPLES:
  3576.     
  3577.         if(!(Csignals() & DSR)) {
  3578.             Cclose();
  3579.             abort("Modem not ready"); }
  3580.     CTESTC                                                           CTESTC
  3581.     
  3582.     
  3583.     
  3584.     PROTOTYPE:
  3585.     
  3586.         int Ctestc()
  3587.     
  3588.     
  3589.     ARGUMENTS:
  3590.     
  3591.         None
  3592.     
  3593.     
  3594.     RETURN VALUE:
  3595.     
  3596.         0-255   - Character read from comm port
  3597.         -1      - No character available
  3598.     
  3599.     
  3600.     DESCRIPTION:
  3601.     
  3602.           This function tests for a character from the  communications  port
  3603.        previously opened with "Copen", and returns that character if one  if
  3604.        found. If no character is available, "Ctestc" returns -1.
  3605.     
  3606.     
  3607.     EXAMPLES:
  3608.     
  3609.         if((c = Ctestc()) == -1) {
  3610.             Cclose();
  3611.             abort("No character available"); }
  3612.     DISABLE                                                         DISABLE
  3613.     
  3614.     
  3615.     
  3616.     PROTOTYPE:
  3617.     
  3618.         disable();
  3619.     
  3620.     
  3621.     ARGUMENTS:
  3622.     
  3623.         None
  3624.     
  3625.     
  3626.     RETURN VALUE:
  3627.     
  3628.         None
  3629.     
  3630.     
  3631.     DESCRIPTION:
  3632.     
  3633.           The  "disable"  function  disables  the  8086  interrupt   system,
  3634.        preventing the  processor  from  servicing  interrupts.  It  is  used
  3635.        whenever the execution of an interrupt handler may interfere  with  a
  3636.        particular operation.
  3637.     
  3638.           When this function is used, the "enable" function should be called
  3639.        as soon as possible after "disable". Failure to do this may result in
  3640.        loss  of  system  functions  performed  under  interrupts,  such   as
  3641.        timekeeping, and serial communications (Via MICRO-C serial drivers).
  3642.     
  3643.     
  3644.     EXAMPLES:
  3645.     
  3646.         disable();                  /* Disallow interrupts */
  3647.         Cflags &= ~TRANSPARENT;     /* Remove transparency */
  3648.         enable();                   /* Re-allow interrupts */
  3649.     ENABLE                                                           ENABLE
  3650.     
  3651.     
  3652.     
  3653.     PROTOTYPE:
  3654.     
  3655.         enable();
  3656.     
  3657.     
  3658.     ARGUMENTS:
  3659.     
  3660.         None
  3661.     
  3662.     
  3663.     RETURN VALUE:
  3664.     
  3665.         None
  3666.     
  3667.     
  3668.     DESCRIPTION:
  3669.     
  3670.           The "enable" function enables the 8086 interrupt system,  allowing
  3671.        the processor to service interrupts. It should be called as  soon  as
  3672.        possible following the use of the "disable" function.
  3673.     
  3674.     
  3675.     EXAMPLES:
  3676.     
  3677.         disable();                  /* Disallow interrupts */
  3678.         Cflags |= TRANSPARENT;      /* Force  transparency */
  3679.         enable();                   /* Re-allow interrupts */
  3680.     EXEC                                                               EXEC
  3681.     
  3682.     
  3683.     
  3684.     PROTOTYPE:
  3685.     
  3686.         int exec(char *exefile, char *args)
  3687.     
  3688.     
  3689.     ARGUMENTS:
  3690.     
  3691.         exefile - Full pathname of a '.COM' or '.EXE' file
  3692.         args    - Command tail containing arguments
  3693.     
  3694.     
  3695.     RETURN VALUE:
  3696.     
  3697.         0 if successful, otherwise an MS-DOS error code
  3698.     
  3699.     
  3700.     DESCRIPTION:
  3701.     
  3702.           The "exec" function causes MS-DOS to suspend the execution of  the
  3703.        MICRO-C program, and then to execute the indicated '.EXE'  or  '.COM'
  3704.        program file. When that program terminates, execution of the  MICRO-C
  3705.        program will resume.
  3706.     
  3707.           This is a low level interface to the MS-DOS 'EXEC'  function,  and
  3708.        as such, it does not search your PATH, does not process '.BAT' files,
  3709.        nor provide any I/O redirection facilities. If you want to  make  use
  3710.        of these features (which are  provided  by  'COMMAND.COM'),  use  the
  3711.        higher level 'SYSTEM' function.
  3712.     
  3713.     
  3714.     EXAMPLES:
  3715.     
  3716.         printf("Type 'EXIT' to return to the MICRO-C program\n");
  3717.         exec("C:\\COMMAND.COM", "");    /* Start up a sub-shell */
  3718.     FREE_SEG                                                       FREE_SEG
  3719.     
  3720.     
  3721.     
  3722.     PROTOTYPE:
  3723.     
  3724.         int free_seg(int segment)
  3725.     
  3726.     
  3727.     ARGUMENTS:
  3728.     
  3729.         segment - A previously allocated segment of memory
  3730.     
  3731.     
  3732.     RETURN VALUE:
  3733.     
  3734.         0       - The segment was released
  3735.         !0      - DOS error code
  3736.     
  3737.     
  3738.     DESCRIPTION:
  3739.     
  3740.           The "free_seg" function releases a segment  of  memory  previously
  3741.        allocated by "alloc_seg", and returns it  to  the  operating  system.
  3742.        This should be used whenever your program has finished with a segment
  3743.        of extra memory which it has allocated.
  3744.     
  3745.     
  3746.     EXAMPLES:
  3747.     
  3748.         aseg = alloc_seg(4096);         /* Allocate a 64K segment */
  3749.         set_es(aseg);                   /* Set up extra segment */
  3750.         asm_func();                     /* Call assembler function */
  3751.         free_seg(aseg);                 /* Releas the memory */
  3752.     GET_ATTR                                                       GET_ATTR
  3753.     
  3754.     
  3755.     
  3756.     PROTOTYPE:
  3757.     
  3758.         int get_attr(char *pathname, int &attrs)
  3759.     
  3760.     
  3761.     ARGUMENTS:
  3762.     
  3763.         pathname- Name of file to get attributes of
  3764.         attrs   - Integer to receive attributes
  3765.     
  3766.     
  3767.     RETURN VALUE:
  3768.     
  3769.         0 if successful, otherwise an operating system error code
  3770.     
  3771.     
  3772.     DESCRIPTION:
  3773.     
  3774.           This function retreives the attributes of the specified file.
  3775.     
  3776.           The meaning of the individual bits in the "attrs" value is defined
  3777.        in the "file.h" header file.
  3778.     
  3779.     
  3780.     EXAMPLES:
  3781.     
  3782.         get_attr("tempfile", &attributes);
  3783.     GET_CS                                                           GET_CS
  3784.     
  3785.     
  3786.     
  3787.     PROTOTYPE:
  3788.     
  3789.         int get_cs()
  3790.     
  3791.     
  3792.     ARGUMENTS:
  3793.     
  3794.         None
  3795.     
  3796.     
  3797.     RETURN VALUE:
  3798.     
  3799.         The current processor CODE segment
  3800.     
  3801.     
  3802.     DESCRIPTION:
  3803.     
  3804.           This function is available only on the 8086 family of  processors,
  3805.        and returns the current processor CODE segment.
  3806.     
  3807.     
  3808.     EXAMPLES:
  3809.     
  3810.         code_seg = get_cs();
  3811.     GET_DATE                                                       GET_DATE
  3812.     
  3813.     
  3814.     
  3815.     PROTOTYPE:
  3816.     
  3817.         get_date(int &day, int &month, int &year)
  3818.     
  3819.     
  3820.     ARGUMENTS:
  3821.     
  3822.         &day    - Address of integer to receive day (1-31)
  3823.         &month  - Address of integer to receive month (1-12)
  3824.         &year   - Address of integer to receive year (1980-2099)
  3825.     
  3826.     
  3827.     RETURN VALUE:
  3828.     
  3829.         None
  3830.     
  3831.     
  3832.     DESCRIPTION:
  3833.     
  3834.           This function gets the current system  date  in  day,  month,  and
  3835.        year.
  3836.     
  3837.     
  3838.     EXAMPLES:
  3839.     
  3840.         get_date(&day, &month, &year);
  3841.         printf("%s %u, %u", months[month], day, year);
  3842.     GET_DRIVE                                                     GET_DRIVE
  3843.     
  3844.     
  3845.     
  3846.     PROTOTYPE:
  3847.     
  3848.         int get_drive()
  3849.     
  3850.     
  3851.     ARGUMENTS:
  3852.     
  3853.         None
  3854.     
  3855.     
  3856.     RETURN VALUE:
  3857.     
  3858.         The currently active (default) disk drive (0=A, 1=B, 2=C, ...)
  3859.     
  3860.     
  3861.     DESCRIPTION:
  3862.     
  3863.           The "get_drive" function returns the  drive  index  (0-n)  of  the
  3864.        currently active or "default" MS-DOS disk drive.
  3865.     
  3866.     
  3867.     EXAMPLES:
  3868.     
  3869.         old_drive = get_drive();
  3870.         set_drive(new_drive);
  3871.     GET_DS                                                           GET_DS
  3872.     
  3873.     
  3874.     
  3875.     PROTOTYPE:
  3876.     
  3877.         int get_ds()
  3878.     
  3879.     
  3880.     ARGUMENTS:
  3881.     
  3882.         None
  3883.     
  3884.     
  3885.     RETURN VALUE:
  3886.     
  3887.         The current processor DATA segment
  3888.     
  3889.     
  3890.     DESCRIPTION:
  3891.     
  3892.           This function is available only on the 8086 family of  processors,
  3893.        and returns the current processor DATA segment.
  3894.     
  3895.     
  3896.     EXAMPLES:
  3897.     
  3898.         data_seg = get_ds();
  3899.     GET_ES                                                           GET_ES
  3900.     
  3901.     
  3902.     
  3903.     PROTOTYPE:
  3904.     
  3905.         int get_es()
  3906.     
  3907.     
  3908.     ARGUMENTS:
  3909.     
  3910.         None
  3911.     
  3912.     
  3913.     RETURN VALUE:
  3914.     
  3915.         The current processor EXTRA segment
  3916.     
  3917.     
  3918.     DESCRIPTION:
  3919.     
  3920.           This function is available only on the 8086 family of  processors,
  3921.        and returns the current processor EXTRA segment.
  3922.     
  3923.     
  3924.     EXAMPLES:
  3925.     
  3926.         code_seg = get_es();
  3927.     GET_TIME                                                       GET_TIME
  3928.     
  3929.     
  3930.     
  3931.     PROTOTYPE:
  3932.     
  3933.         get_time(int &hour, int &minite, int &second)
  3934.     
  3935.     
  3936.     ARGUMENTS:
  3937.     
  3938.         &hour   - Address of integer to receive hour (0-23)
  3939.         &minite - Address of integer to receive minite (0-59)
  3940.         &second - Address of integer to receive second (0-59)
  3941.     
  3942.     
  3943.     RETURN VALUE:
  3944.     
  3945.         None
  3946.     
  3947.     
  3948.     DESCRIPTION:
  3949.     
  3950.           This function gets the current system time in hours,  minites  and
  3951.        seconds.
  3952.     
  3953.     
  3954.     EXAMPLES:
  3955.     
  3956.         get_time(&hour, &minite, &second);
  3957.         printf("%02:%02:%02", hour, minite, second);
  3958.     RESIZE_SEG                                                   RESIZE_SEG
  3959.     
  3960.     
  3961.     
  3962.     PROTOTYPE:
  3963.     
  3964.         int resize_seg(int segment, int size)
  3965.     
  3966.     
  3967.     ARGUMENTS:
  3968.     
  3969.         segment - A previously allocated segment of memory
  3970.         size    - Desired size (in 16 byte paragraphs)
  3971.     
  3972.     
  3973.     RETURN VALUE:
  3974.     
  3975.         0       - The segments size has been adjusted
  3976.         !0      - DOS error code
  3977.     
  3978.     
  3979.     DESCRIPTION:
  3980.     
  3981.           The "resize_seg" function provides a method of changing  the  size
  3982.        of a segment of memory previously allocated via "alloc_seg".  If  not
  3983.        enough memory is available, the function will fail  with  a  ono-zero
  3984.        return value.
  3985.     
  3986.           This function may also be used to adjust the memoey allocation  of
  3987.        the programs image, by passing it the segment address of the programs
  3988.        own PSP. This value is available in the external variable "PSP".
  3989.     
  3990.           MICRO-C normally allocates 64K for programs compiled in  the  TINY
  3991.        model, and (64K + (256 byte PSP) + (size  of  executable  code))  for
  3992.        programs compiled in the SMALL model. This allocation should NEVER be
  3993.        reduced, however you may enlarge it if your program wishes to  access
  3994.        additional data immediately following its own DATA/STACK segment.
  3995.     
  3996.     
  3997.     EXAMPLES:
  3998.     
  3999.         extern int PSP;
  4000.     
  4001.         main()
  4002.         {
  4003.             if(resize_seg(PSP, 8192))   /* Append 64K buffer */
  4004.                 abort("Not enough memory!!!");
  4005.             ...     /* Remainder of program */
  4006.         }
  4007.     RESTORE_VIDEO                                             RESTORE_VIDEO
  4008.     
  4009.     
  4010.     
  4011.     PROTOTYPE:
  4012.     
  4013.         restore_video(char buffer[4006]);
  4014.     
  4015.     
  4016.     ARGUMENTS:
  4017.     
  4018.         buffer  - Video save area.
  4019.     
  4020.     
  4021.     RETURN VALUE:
  4022.     
  4023.         None
  4024.     
  4025.     
  4026.     DESCRIPTION:
  4027.     
  4028.           The RESTORE_VIDEO function restores the contents and state of  the
  4029.        IBM P.C. video display to the state it was in when  "SAVE_VIDEO"  was
  4030.        executed. At the present time, the function  is  effective  only  for
  4031.        text modes. Graphics screens will not be restored, due  to  the  high
  4032.        memory requirements.
  4033.     
  4034.           Although this function is useful in ANY program  (to  restore  the
  4035.        DOS screen before termination), it is most  useful  in  "POP-UP"  ram
  4036.        resident programs (See "TSR" function), to save  the  screen  of  any
  4037.        application which may be running when you pop up.
  4038.     
  4039.           The video state is restored from  the  passed  "buffer"  argument,
  4040.        which is 4006 bytes  in  size,  and  must  have  been  filled  in  by
  4041.        "SAVE_VIDEO". It has the following format:
  4042.     
  4043.                   buffer[0]         - Video mode
  4044.                     "   [1]         - Video page
  4045.                     "   [2]         - 'X' cursor position
  4046.                     "   [3]         - 'Y' cursor position
  4047.                     "   [4]         - Ending line for cursor
  4048.                     "   [5]         - Starting line for cursor
  4049.                     "   [6-4005]    - Saved video screen contents
  4050.     
  4051.     
  4052.     EXAMPLES:
  4053.     
  4054.         popup_func()
  4055.         {
  4056.             save_video();
  4057.             perform_function();
  4058.             restore_video();
  4059.         }
  4060.     SAVE_VIDEO                                                   SAVE_VIDEO
  4061.     
  4062.     
  4063.     
  4064.     PROTOTYPE:
  4065.     
  4066.         save_video(char buffer[4006]);
  4067.     
  4068.     
  4069.     ARGUMENTS:
  4070.     
  4071.         buffer  - Video save area.
  4072.     
  4073.     
  4074.     RETURN VALUE:
  4075.     
  4076.         None
  4077.     
  4078.     
  4079.     DESCRIPTION:
  4080.     
  4081.           The SAVE_VIDEO function saves the current contents  and  state  of
  4082.        the IBM P.C. video display. The screen may be restored  at  any  time
  4083.        using "RESTORE_VIDEO". At the present time, the function is effective
  4084.        only for text modes. Graphics screens will not be saved, due  to  the
  4085.        high memory requirements.
  4086.     
  4087.           Although this function is useful in ANY program  (to  restore  the
  4088.        DOS screen before termination), it is most  useful  in  "POP-UP"  ram
  4089.        resident programs (See "TSR" function), to save  the  screen  of  any
  4090.        application which may be running when you pop up.
  4091.     
  4092.           The video state is saved in the passed "buffer" argument, which is
  4093.        4006 bytes in size, and has the following format:
  4094.     
  4095.                   buffer[0]         - Video mode
  4096.                     "   [1]         - Video page
  4097.                     "   [2]         - 'X' cursor position
  4098.                     "   [3]         - 'Y' cursor position
  4099.                     "   [4]         - Ending line for cursor
  4100.                     "   [5]         - Starting line for cursor
  4101.                     "   [6-4005]    - Saved video screen contents
  4102.     
  4103.     
  4104.     EXAMPLES:
  4105.     
  4106.         popup_func()
  4107.         {
  4108.             save_video();
  4109.             perform_function();
  4110.             restore_video();
  4111.         }
  4112.     SET_ATTR                                                       SET_ATTR
  4113.     
  4114.     
  4115.     
  4116.     PROTOTYPE:
  4117.     
  4118.         int set_attr(char *pathname, int attrs)
  4119.     
  4120.     
  4121.     ARGUMENTS:
  4122.     
  4123.         pathname- Name of file to get attributes of
  4124.         attrs   - New attributes
  4125.     
  4126.     
  4127.     RETURN VALUE:
  4128.     
  4129.         0 if successful, otherwise an operating system error code
  4130.     
  4131.     
  4132.     DESCRIPTION:
  4133.     
  4134.           This function sets the system attributes of the specified file.
  4135.     
  4136.           The meaning of the individual bits in the "attrs" value is defined
  4137.        in the "file.h" header file.
  4138.     
  4139.     
  4140.     EXAMPLES:
  4141.     
  4142.         set_attr("tempfile", READONLY|HIDDEN);
  4143.     SET_DATE                                                       SET_DATE
  4144.     
  4145.     
  4146.     
  4147.     PROTOTYPE:
  4148.     
  4149.         set_date(int day, int month, int year)
  4150.     
  4151.     
  4152.     ARGUMENTS:
  4153.     
  4154.         day     - New day (1-31)
  4155.         month   - New month (1-12)
  4156.         year    - New year (1980-2099)
  4157.     
  4158.     
  4159.     RETURN VALUE:
  4160.     
  4161.         0       - Success
  4162.         -1      - Invalid date given
  4163.     
  4164.     
  4165.     DESCRIPTION:
  4166.     
  4167.           This function sets the current system  date  to  day,  month,  and
  4168.        year.
  4169.     
  4170.     
  4171.     EXAMPLES:
  4172.     
  4173.         set_date(1, 1, 1980);   /* Set to Jan 1, 1980 */
  4174.     SET_DRIVE                                                     SET_DRIVE
  4175.     
  4176.     
  4177.     
  4178.     PROTOTYPE:
  4179.     
  4180.         int set_drive(int drive)
  4181.     
  4182.     
  4183.     ARGUMENTS:
  4184.     
  4185.         Drive   - New drive index (0=A, 1=B, 2=C ...)
  4186.     
  4187.     
  4188.     RETURN VALUE:
  4189.     
  4190.         The total number of "logical" disk drives in the system
  4191.     
  4192.     
  4193.     DESCRIPTION:
  4194.     
  4195.           The "set_drive" function sets the  disk  drive  indicated  by  the
  4196.        "drive" index (0-x) to be the currently active  or  "default"  MS-DOS
  4197.        disk drive.
  4198.     
  4199.     
  4200.     EXAMPLES:
  4201.     
  4202.         old_drive = get_drive();
  4203.         set_drive(new_drive);
  4204.     SET_ES                                                           SET_ES
  4205.     
  4206.     
  4207.     
  4208.     PROTOTYPE:
  4209.     
  4210.         int set_es(int segment)
  4211.     
  4212.     
  4213.     ARGUMENTS:
  4214.     
  4215.         segment - The 16 bit new segment value
  4216.     
  4217.     
  4218.     RETURN VALUE:
  4219.     
  4220.         None
  4221.     
  4222.     
  4223.     DESCRIPTION:
  4224.     
  4225.           This function is available only on the 8086 family of  processors,
  4226.        and sets the processors EXTRA segment to the indicated value.
  4227.     
  4228.     
  4229.     EXAMPLES:
  4230.     
  4231.         set_es(get_ds());       /* Copy DATA to EXTRA segments */
  4232.     SET_TIME                                                       SET_TIME
  4233.     
  4234.     
  4235.     
  4236.     PROTOTYPE:
  4237.     
  4238.         set_time(int hour, int minite, int second)
  4239.     
  4240.     
  4241.     ARGUMENTS:
  4242.     
  4243.         hour    - New hour (0-23)
  4244.         minite  - New minite (0-59)
  4245.         second  - New second (0-59)
  4246.     
  4247.     
  4248.     RETURN VALUE:
  4249.     
  4250.         0       - Success
  4251.         -1      - Invalid time given
  4252.     
  4253.     
  4254.     DESCRIPTION:
  4255.     
  4256.           This function sets the current system time to "hour", "minite" and
  4257.        "second".
  4258.     
  4259.     
  4260.     EXAMPLES:
  4261.     
  4262.         set_time(0, 0, 0);  /* Set to 00:00:00 (midnight) */
  4263.     TSR                                                                 TSR
  4264.     
  4265.     
  4266.     
  4267.     PROTOTYPE:
  4268.     
  4269.         tsr(&func, int hotkey, int alloc)
  4270.     
  4271.     
  4272.     ARGUMENTS:
  4273.     
  4274.         func    - Address of function to execute
  4275.         hotkey  - POP-UP activation hotkeys
  4276.         alloc   - Memory allocation
  4277.     
  4278.     
  4279.     RETURN VALUE:
  4280.     
  4281.         Function normally never returns, but if it does, an
  4282.         operating system error code is passed back.
  4283.     
  4284.     
  4285.     DESCRIPTION:
  4286.     
  4287.           The TSR function terminates the MICRO-C  program,  but  leaves  it
  4288.        resident in memory. When the specified "HOT KEYS" are detected on the
  4289.        IBM PC keyboard, the context of whatever program is running is saved,
  4290.        and the specified MICRO-C function  is  called.  When  that  function
  4291.        returns, the interrupted program is resumed.
  4292.     
  4293.           When activated this way, THE "func" FUNCTION  MUST  NOT  TERMINATE
  4294.        WITH "exit" or one of its related functions (abort  etc.).  THE  ONLY
  4295.        WAY IT MAY TERMINATE IS TO "return" NORMALLY.
  4296.     
  4297.           The meaning of "hotkey" is defined in the "tsr.h" header file.
  4298.     
  4299.           The "alloc" paremeter specifies how much extra  memory  is  to  be
  4300.        retained in the TSR image for use  by  the  MICRO-C  stack  and  heap
  4301.        memory allocation functions. The "func" function(s) must insure  that
  4302.        the total amount of memory used by the stack and  calls  to  "malloc"
  4303.        does not exceed this value.
  4304.     
  4305.           NOTE: "malloc" will fail if the heap grows to  within  1K  of  the
  4306.        stack pointer.
  4307.     
  4308.           All memory used by  code,  global  variables,  string  space,  and
  4309.        "malloc" calls prior to the use of "tsr" is  automatically  retained,
  4310.        and should not be included in the "alloc" value.
  4311.     
  4312.           TSR programs which perform screen I/O should take care to save and
  4313.        restore the screen contents when popping up and down.
  4314.     
  4315.     
  4316.     EXAMPLES:
  4317.     
  4318.         tsr(&popup_func, ALT+L_SHIFT, 1024);
  4319.     VCLEAR_BOX                                                   VCLEAR_BOX
  4320.     
  4321.     
  4322.     
  4323.     PROTOTYPE:
  4324.     
  4325.         vclear_box(int x, int y, int w, int h)
  4326.     
  4327.     
  4328.     ARGUMENTS:
  4329.     
  4330.         x       - COLUMN of top left corner of box
  4331.         y       - ROW of top left corner of box
  4332.         w       - Width of box (columns)
  4333.         h       - Height of box (rows)
  4334.     
  4335.     
  4336.     RETURN VALUE:
  4337.     
  4338.         None
  4339.     
  4340.     
  4341.     DESCRIPTION:
  4342.     
  4343.           This function clears a box of the specified height and  width,  at
  4344.        the indicated 'X' and 'Y' coordinates, on  the  IBM-PC  video  screen
  4345.        using the block graphics characters. The entire  box  is  cleared  to
  4346.        spaces.
  4347.     
  4348.           "VOPEN" MUST be called prior to using this function.
  4349.     
  4350.     
  4351.     EXAMPLES:
  4352.     
  4353.         vclear_box(21, 11, 8, 3);   /* Clear a BOX */
  4354.     VCLEOL                                                           VCLEOL
  4355.     
  4356.     
  4357.     
  4358.     PROTOTYPE:
  4359.     
  4360.         vcleol()
  4361.     
  4362.     
  4363.     ARGUMENTS:
  4364.     
  4365.         None
  4366.     
  4367.     
  4368.     RETURN VALUE:
  4369.     
  4370.         None
  4371.     
  4372.     
  4373.     DESCRIPTION:
  4374.     
  4375.           This function clears the IBM PC  video  screen  from  the  current
  4376.        cursor position to the end of a line.
  4377.     
  4378.           You must "#include video.h", and execute "VOPEN"  prior  to  using
  4379.        this function.
  4380.     
  4381.     
  4382.     EXAMPLES:
  4383.     
  4384.         vprintf("Input> ");     /* Display a prompt */
  4385.         vcleol();               /* Clear remainder of input line */
  4386.     VCLEOS                                                           VCLEOS
  4387.     
  4388.     
  4389.     
  4390.     PROTOTYPE:
  4391.     
  4392.         vcleos()
  4393.     
  4394.     
  4395.     ARGUMENTS:
  4396.     
  4397.         None
  4398.     
  4399.     
  4400.     RETURN VALUE:
  4401.     
  4402.         None
  4403.     
  4404.     
  4405.     DESCRIPTION:
  4406.     
  4407.           This function clears the IBM PC  video  screen  from  the  current
  4408.        cursor position to the end of a screen.
  4409.     
  4410.           "VOPEN" MUST be called prior to using this function.
  4411.     
  4412.     
  4413.     EXAMPLES:
  4414.     
  4415.         vgotoxy(0, 10);         /* position at line 11 */
  4416.         vcleos();               /* Clear lower part of screen */
  4417.     VCLSCR                                                           VCLSCR
  4418.     
  4419.     
  4420.     
  4421.     PROTOTYPE:
  4422.     
  4423.         vclscr()
  4424.     
  4425.     
  4426.     ARGUMENTS:
  4427.     
  4428.         None
  4429.     
  4430.     
  4431.     RETURN VALUE:
  4432.     
  4433.         None
  4434.     
  4435.     
  4436.     DESCRIPTION:
  4437.     
  4438.           This function clears the entire IBM PC video screen and resets the
  4439.        cursor position to the top left hand corner.
  4440.     
  4441.           "VOPEN" MUST be called prior to using this function.
  4442.     
  4443.     
  4444.     EXAMPLES:
  4445.     
  4446.         if(c = 0x1b) {          /* Escape command */
  4447.             vclscr();       /* Clear the screen */
  4448.             vprintf("%s has terminated\n", argv[0]);
  4449.             exit(-1); }
  4450.     VCURSOR_BLOCK                                             VCURSOR_BLOCK
  4451.     
  4452.     
  4453.     
  4454.     PROTOTYPE:
  4455.     
  4456.         vcursor_block()
  4457.     
  4458.     
  4459.     ARGUMENTS:
  4460.     
  4461.         None
  4462.     
  4463.     
  4464.     RETURN VALUE:
  4465.     
  4466.         None
  4467.     
  4468.     
  4469.     DESCRIPTION:
  4470.     
  4471.           This function enables (turns on) display of the cursor on the  IBM
  4472.        PC video display. The cursor is shown as  flashing  block,  occupying
  4473.        the entire character window.
  4474.     
  4475.           "VOPEN" MUST be called prior to using this function.
  4476.     
  4477.     
  4478.     EXAMPLES:
  4479.     
  4480.         if(insert)              /* Test insert mode flag */
  4481.             vcursor_block();    /* Indicate inserting with block cursor */
  4482.         else
  4483.             vcursor_line();     /* Indicate overwrite with line cursor */
  4484.     VCURSOR_LINE                                               VCURSOR_LINE
  4485.     
  4486.     
  4487.     
  4488.     PROTOTYPE:
  4489.     
  4490.         vcursor_line()
  4491.     
  4492.     
  4493.     ARGUMENTS:
  4494.     
  4495.         None
  4496.     
  4497.     
  4498.     RETURN VALUE:
  4499.     
  4500.         None
  4501.     
  4502.     
  4503.     DESCRIPTION:
  4504.     
  4505.           This function enables (turns on) display of the cursor on the  IBM
  4506.        PC video display. The cursor is shown as a single flashing  line,  at
  4507.        the bottom of the character window.
  4508.     
  4509.           "VOPEN" MUST be called prior to using this function.
  4510.     
  4511.     
  4512.     EXAMPLES:
  4513.     
  4514.         vcursor_line();     /* Re-enable the cursor */
  4515.         exit(0);            /* And terminate */
  4516.     VCURSOR_OFF                                                 VCURSOR_OFF
  4517.     
  4518.     
  4519.     
  4520.     PROTOTYPE:
  4521.     
  4522.         vcursor_off()
  4523.     
  4524.     
  4525.     ARGUMENTS:
  4526.     
  4527.         None
  4528.     
  4529.     
  4530.     RETURN VALUE:
  4531.     
  4532.         None
  4533.     
  4534.     
  4535.     DESCRIPTION:
  4536.     
  4537.           This function inhibits (turns off) display of the  cursor  on  the
  4538.        IBM PC video display. This affects the cursor  display  only,  screen
  4539.        output will continue to be displayed at the correct cursor position.
  4540.     
  4541.           "VOPEN" MUST be called prior to using this function.
  4542.     
  4543.     
  4544.     EXAMPLES:
  4545.     
  4546.         vclscr();           /* Clear screen */
  4547.         vcursor_off();      /* Inhibit cursor */
  4548.         vmenu(10, 10, main_menu, 0, &index);    /* Present main menu */
  4549.     VDRAW_BOX                                                     VDRAW_BOX
  4550.     
  4551.     
  4552.     
  4553.     PROTOTYPE:
  4554.     
  4555.         vdraw_box(int x, int y, int w, int h)
  4556.     
  4557.     
  4558.     ARGUMENTS:
  4559.     
  4560.         x       - COLUMN of top left corner of box
  4561.         y       - ROW of top left corner of box
  4562.         w       - Width of box (columns)
  4563.         h       - Height of box (rows)
  4564.     
  4565.     
  4566.     RETURN VALUE:
  4567.     
  4568.         None
  4569.     
  4570.     
  4571.     DESCRIPTION:
  4572.     
  4573.           This function draws a box of the specified height  and  width,  at
  4574.        the indicated 'X' and 'Y' coordinates, on  the  IBM-PC  video  screen
  4575.        using the block graphics characters.
  4576.     
  4577.           "VOPEN" MUST be called prior to using this function.
  4578.     
  4579.     
  4580.     EXAMPLES:
  4581.     
  4582.         vdraw_box(20, 10, 10, 5);   /* Draw a BOX */
  4583.     VERSION                                                         VERSION
  4584.     
  4585.     
  4586.     
  4587.     PROTOTYPE:
  4588.     
  4589.         int version()
  4590.     
  4591.     
  4592.     ARGUMENTS:
  4593.     
  4594.         None
  4595.     
  4596.     
  4597.     RETURN VALUE:
  4598.     
  4599.         MS-DOS operating system version number
  4600.     
  4601.     
  4602.     DESCRIPTION:
  4603.     
  4604.           The "version" function is available only under MS-DOS, and returns
  4605.        the version number of the operating system.
  4606.     
  4607.           The higher 8 bits  of  the  returned  value  indicates  the  MAJOR
  4608.        version number ('3' in DOS 3.1)
  4609.     
  4610.           The lower 8 bits of the returned value indicates the MINOR version
  4611.        nuber ('1' in DOS 3.1).
  4612.     
  4613.     
  4614.     EXAMPLES:
  4615.     
  4616.         if(version() < 0x031E)
  4617.             abort("Requires DOS 3.30 or higher\n");
  4618.     VGETC                                                             VGETC
  4619.     
  4620.     
  4621.     
  4622.     PROTOTYPE:
  4623.     
  4624.         int vgetc()
  4625.     
  4626.     
  4627.     ARGUMENTS:
  4628.     
  4629.         None
  4630.     
  4631.     
  4632.     RETURN VALUE:
  4633.     
  4634.         0-127   - ASCII value of key pressed
  4635.         < 0     - Special function key as defined in "video.h"
  4636.     
  4637.     
  4638.     DESCRIPTION:
  4639.     
  4640.           The "vgetc" function waits until a key is pressed  on  the  system
  4641.        console, and returns its value.
  4642.     
  4643.           Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
  4644.        keypress will be reported, even if the VGETC function is called after
  4645.        a key is pressed and released.
  4646.     
  4647.     
  4648.     EXAMPLES:
  4649.     
  4650.         switch(vgetc()) {       /* Handle input keys
  4651.                 . . .
  4652.         }
  4653.     VGETS                                                             VGETS
  4654.     
  4655.     
  4656.     
  4657.     PROTOTYPE:
  4658.     
  4659.         int vgets(int x, int y, char *prompt, char *field, int width)
  4660.     
  4661.     
  4662.     ARGUMENTS:
  4663.     
  4664.         x       - COLUMN of top left corner of input box
  4665.         y       - ROW of top left corner of input box
  4666.         prompt  - String to prompt with
  4667.         field   - String to receive the data
  4668.         width   - Width in characters of input field
  4669.     
  4670.     
  4671.     RETURN VALUE:
  4672.     
  4673.         0   - Selection was made and ENTER pressed.
  4674.         !0  - Input was aborted via ESCAPE key.
  4675.     
  4676.     
  4677.     DESCRIPTION:
  4678.     
  4679.           The "vgets" function draws a  box  on  the  video  screen  at  the
  4680.        specified X and Y coordinates, then prompts for and receives an input
  4681.        string in the box. The box is  drawn  large  enough  to  contain  the
  4682.        prompt and  the  specified  width  of  input  field.  The  prompt  is
  4683.        displayed at the left hand  side  of  the  box,  and  the  cursor  is
  4684.        positioned immediatly following it, at the start of the input field.
  4685.     
  4686.           The "field" parameter is the  address  of  a  character  array  to
  4687.        receive the input string. The previous value of the "field" array  is
  4688.        inserted into the input box when VGETS is invoked. If you do not want
  4689.        to display an old value, you should set the first  character  pointed
  4690.        to by field to zero, before calling VGETS.
  4691.     
  4692.           When entering the string, the user may use the  following  special
  4693.        keys to edit the input field:
  4694.     
  4695.                 Right Arrow - Move forward one character
  4696.                 Left  Arrow - Move backward one character
  4697.                 Delete      - Delete the character under the cursor
  4698.                 Backspace   - Move backward one character and delete.
  4699.                 Home        - Move to beginning of string
  4700.                 End         - Move to end of string
  4701.                 PgUp        - Clear (erase) entire string
  4702.                 PgDn        - Clear from cursor to end of string
  4703.                 Enter       - Accept (enter) the string
  4704.                 ESC         - Abort the input request
  4705.     
  4706.           All data entered in the input box is inserted into any data  which
  4707.        is already present.
  4708.     
  4709.     
  4710.     
  4711.     EXAMPLES:
  4712.     
  4713.         name[0] = 0;
  4714.         if(vgets(10, 10, "Your name?", name, 30))
  4715.             return;     /* Aborted, exit to higher level */
  4716.     VGOTOXY                                                         VGOTOXY
  4717.     
  4718.     
  4719.     
  4720.     PROTOTYPE:
  4721.     
  4722.         vgotoxy(int x, int y)
  4723.     
  4724.     
  4725.     ARGUMENTS:
  4726.     
  4727.         x       - New COLUMN (0-79)
  4728.         y       - New ROW    (0-24)
  4729.     
  4730.     
  4731.     RETURN VALUE:
  4732.     
  4733.         None
  4734.     
  4735.     
  4736.     DESCRIPTION:
  4737.     
  4738.           The "vgotoxy" function positions the cursor on  the  IBM-PC  video
  4739.        screen. Any further display output will occur  at  the  new  ROW  and
  4740.        COLUMN on the screen.
  4741.     
  4742.           The extern "int" variable "V_XY" may be referenced to read or  set
  4743.        the  current  X/Y  position.  The  higher  8  bits  contain  the  'Y'
  4744.        coordinate, and the lower 8 bits contain the 'X' coordinate. If  this
  4745.        variable is used to set (restore) the  cursor  position,  "vupdatexy"
  4746.        must then be called to position the physical cursor.
  4747.     
  4748.           "VOPEN" MUST be called prior to using this function.
  4749.     
  4750.     
  4751.     EXAMPLES:
  4752.     
  4753.         for(i=0; i<24; ++i) {   /* Draw a diagonal line of 'X's */
  4754.             vgotoxy(i, i);
  4755.             vputc('X'); }
  4756.     VMENU                                                             VMENU
  4757.     
  4758.     
  4759.     
  4760.     PROTOTYPE:
  4761.     
  4762.         vmenu(int x, int y, char *names[], char erase, int &index)
  4763.     
  4764.     
  4765.     ARGUMENTS:
  4766.     
  4767.         x       - COLUMN of top left corner of menu box
  4768.         y       - ROW of top left corner of menu box
  4769.         names   - Array to menu selection text (last entry = 0)
  4770.         erase   - 1=Erase BOX after selection is made
  4771.         index   - Address of message selection index variable
  4772.     
  4773.     
  4774.     RETURN VALUE:
  4775.     
  4776.         0   - Selection was made and ENTER pressed.
  4777.         !0  - Menu was aborted via ESCAPE key.
  4778.     
  4779.     
  4780.     DESCRIPTION:
  4781.     
  4782.           The "vmenu" function displays a list of menu items enclosed  in  a
  4783.        box on the IBM-PC video  screen  at  the  specified  ROW  and  COLUMN
  4784.        address. The user may use the UP, DOWN, HOME and END keys  to  select
  4785.        an entry by moving the INVERSE VIDEO selection cursor.
  4786.     
  4787.           When the desired selection is under the cursor, the  selection  is
  4788.        made by pressing the ENTER key.
  4789.     
  4790.           At any time the menu selection may be  canceled  by  pressing  the
  4791.        ESCAPE key.
  4792.     
  4793.           The "names" argument must be a pointer to an  array  of  character
  4794.        strings which are the selections to display. This array MUST end with
  4795.        a zero (0) element to indicate the end of the list.
  4796.     
  4797.           The "erase" flag indicates that the menu box should be cleared  to
  4798.        blanks when the selection is made. If "erase=0", the menu box is left
  4799.        on the screen, WITHOUT the selection cursor, with the selected  entry
  4800.        marked by '>' and '<'. The menu box is always erased when the menu is
  4801.        aborted with the ESCAPE key.
  4802.     
  4803.           The "index" argument is the address of  an  "int"  variable  which
  4804.        contains the position of the selection cursor. It controls where  the
  4805.        selection cursor will appear when the function is first invoked (0  =
  4806.        first entry), and also is assigned  the  position  of  the  selection
  4807.        cursor when the selection is made.
  4808.     
  4809.     
  4810.     
  4811.     EXAMPLES:
  4812.     
  4813.         char *names[] = { "One", "Two", "Three", "Four", "Five", 0 };
  4814.             . . .
  4815.         index = 0;
  4816.         if(vmenu(10, 10, names, 0, &index))
  4817.             return;         /* Aborted, exit to higher level */
  4818.         switch(index) {     /* Handle selection */
  4819.             . . .
  4820.         }
  4821.     VMESSAGE                                                       VMESSAGE
  4822.     
  4823.     
  4824.     
  4825.     PROTOTYPE:
  4826.     
  4827.         vmessage(int x, int y, char *string)
  4828.     
  4829.     
  4830.     ARGUMENTS:
  4831.     
  4832.         x       - COLUMN of top left corner of message box
  4833.         y       - ROW of top left corner of message box
  4834.         string  - Message to display
  4835.     
  4836.     
  4837.     RETURN VALUE:
  4838.     
  4839.         None
  4840.     
  4841.     
  4842.     DESCRIPTION:
  4843.     
  4844.           The "vmessage" function displays a text  string  surrounded  by  a
  4845.        BOX, on the IBM-PC video screen, at  the  specified  ROW  and  COLUMN
  4846.        address.
  4847.     
  4848.           "VOPEN" MUST be called prior to using this function.
  4849.     
  4850.     
  4851.     EXAMPLES:
  4852.     
  4853.         vmessage(20, 20, "Press any KEY to continue");
  4854.         get_key();
  4855.         vclear_box(20, 20, 26, 2);
  4856.     VOPEN                                                             VOPEN
  4857.     
  4858.     
  4859.     
  4860.     PROTOTYPE:
  4861.     
  4862.         vopen()
  4863.     
  4864.     
  4865.     ARGUMENTS:
  4866.     
  4867.         None
  4868.     
  4869.     
  4870.     RETURN VALUE:
  4871.     
  4872.         None
  4873.     
  4874.     
  4875.     DESCRIPTION:
  4876.     
  4877.           This function initializes the IBM-PC video display adapter for use
  4878.        with the MICRO-C video library functions. It determines  the  adapter
  4879.        type  (COLOR  ot  MONOCHROME),  sets  up  internal   variables   with
  4880.        information required by the other video  functions,  and  clears  the
  4881.        video screen.
  4882.     
  4883.           This function MUST  be  called  before  any  of  the  other  video
  4884.        functions in the library are used.
  4885.     
  4886.           After "vopen" is called, the extern "int" variable "V_BASE" may be
  4887.        referenced to determine the memory segment of the video display (B000
  4888.        for monochrome, B800 for color).
  4889.     
  4890.           Any program using the video library  functions  must  include  the
  4891.        "video.h" header file.
  4892.     
  4893.     
  4894.     EXAMPLES:
  4895.     
  4896.         vopen();
  4897.     VPRINTF                                                         VPRINTF
  4898.     
  4899.     
  4900.     
  4901.     PROTOTYPE:
  4902.     
  4903.         register vprintf(char *format, arg, ...)
  4904.     
  4905.     
  4906.     ARGUMENTS:
  4907.     
  4908.         format  - Pointer to format string
  4909.         arg     - Argument as determined by format string
  4910.         ...     - Additional arguments may be required
  4911.     
  4912.     
  4913.     RETURN VALUE:
  4914.     
  4915.         None
  4916.     
  4917.     
  4918.     DESCRIPTION:
  4919.     
  4920.           This function performs exactly as the  "PRINTF"  function  in  the
  4921.        standard function library, except that it  outputs  directly  to  the
  4922.        video screen using the video interface library routines.
  4923.     
  4924.           This function should be used in preference to "PRINTF" when  using
  4925.        the video function library since "PRINTF" will  not  move  the  video
  4926.        librarys cursor.
  4927.     
  4928.           NOTE: This function uses a variable number of arguments, and  must
  4929.        be declared as "register" (See "video.h").
  4930.     
  4931.           "VOPEN" MUST be called prior to using this function.
  4932.     
  4933.     
  4934.     EXAMPLES:
  4935.     
  4936.         vgotoxy(0, 0);
  4937.         vprintf("Screen %u", screen);
  4938.     VPUTC                                                             VPUTC
  4939.     
  4940.     
  4941.     
  4942.     PROTOTYPE:
  4943.     
  4944.         vputc(char chr)
  4945.     
  4946.     
  4947.     ARGUMENTS:
  4948.     
  4949.         chr     - Character to display
  4950.     
  4951.     
  4952.     RETURN VALUE:
  4953.     
  4954.         None
  4955.     
  4956.     
  4957.     DESCRIPTION:
  4958.     
  4959.           This function displays a character on  the  video  screen  at  the
  4960.        current cursor position.
  4961.     
  4962.           Characters are output in "tty" fashion, with  proper  handling  of
  4963.        control codes such as CARRIAGE-RETURN, LINE-FEED and BELL. The screen
  4964.        will scroll upwards when a NEWLINE is printed on the bottom  line  of
  4965.        the screen, or when the bottom line wraps around to the next.
  4966.     
  4967.           Although only the lower 8 bits of a passed value are used, "vputc"
  4968.        will not perform ANY output translations if any of the upper  8  bits
  4969.        are set. This provides a method of displaying  the  video  characters
  4970.        represented by control codes such as NEWLINE, and BACKSPACE.
  4971.     
  4972.           The external "char" variable "V_ATTR" may be used to set the video
  4973.        attribute used by "VPUTC" to display the  character.  This  value  is
  4974.        written to the attribute location associated with  the  character  on
  4975.        the video display hardware. Its effect  is  dependant  on  the  video
  4976.        adapter in use. The "video.h" header file contains definitions of the
  4977.        attribute bits for use on "standard" monochrome and color displays.
  4978.     
  4979.     
  4980.           "VOPEN" MUST be called prior to using this function.
  4981.     
  4982.     
  4983.     EXAMPLES:
  4984.     
  4985.         vputc(0x0A);            /* Line-feed, advance cursor */
  4986.         vputc(0x0A | 0xff00);   /* Display 0x0A character code */
  4987.     VPUTF                                                             VPUTF
  4988.     
  4989.     
  4990.     
  4991.     PROTOTYPE:
  4992.     
  4993.         vputf(char *string, int width)
  4994.     
  4995.     
  4996.     ARGUMENTS:
  4997.     
  4998.         string  - Pointer to character string
  4999.         width   - Width of output field
  5000.     
  5001.     
  5002.     RETURN VALUE:
  5003.     
  5004.         None
  5005.     
  5006.     
  5007.     DESCRIPTION:
  5008.     
  5009.           The "vputf" function outputs a  character  string  to  the  IBM-PC
  5010.        video screen using the video library functions.
  5011.     
  5012.           The string is left justified in a field of the specified width. If
  5013.        the string is shorter than "width", the field is padded with  blanks.
  5014.        If the string is longer than "width", the output is truncated.
  5015.     
  5016.           "VOPEN" MUST be called prior to using this function.
  5017.     
  5018.     
  5019.     EXAMPLES:
  5020.     
  5021.         vputf(message, 10); 
  5022.     VPUTS                                                             VPUTS
  5023.     
  5024.     
  5025.     
  5026.     PROTOTYPE:
  5027.     
  5028.         vputs(char *string)
  5029.     
  5030.     
  5031.     ARGUMENTS:
  5032.     
  5033.         string  - Pointer to character string
  5034.     
  5035.     
  5036.     RETURN VALUE:
  5037.     
  5038.         None
  5039.     
  5040.     
  5041.     DESCRIPTION:
  5042.     
  5043.           The "vputs" function outputs a  character  string  to  the  IBM-PC
  5044.        video screen using the video library functions.
  5045.     
  5046.           "VOPEN" MUST be called prior to using this function.
  5047.     
  5048.     
  5049.     EXAMPLES:
  5050.     
  5051.         vputs(message);
  5052.     VTSTC                                                             VTSTC
  5053.     
  5054.     
  5055.     
  5056.     PROTOTYPE:
  5057.     
  5058.         int vtstc()
  5059.     
  5060.     
  5061.     ARGUMENTS:
  5062.     
  5063.         None
  5064.     
  5065.     
  5066.     RETURN VALUE:
  5067.     
  5068.         0       - No key pressed
  5069.         1-127   - ASCII value of key pressed
  5070.         < 0     - Special function key as defined in "video.h"
  5071.     
  5072.     
  5073.     DESCRIPTION:
  5074.     
  5075.           The "vtstc" function  tests  for  a  key  pressed  on  the  system
  5076.        console, and  returns  its  value.  A  returned  value  of  zero  (0)
  5077.        indicates that no key was found to be pressed.
  5078.     
  5079.           Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
  5080.        keypress will be reported, even if the VTSTC function is called after
  5081.        a key is pressed and released.
  5082.     
  5083.     
  5084.     EXAMPLES:
  5085.     
  5086.         if(vtstc() == 0x1B) /* exit loop on ESCAPE key */
  5087.             break;
  5088.     VUPDATEXY                                                     VUPDATEXY
  5089.     
  5090.     
  5091.     
  5092.     PROTOTYPE:
  5093.     
  5094.         vupdatexy()
  5095.     
  5096.     
  5097.     ARGUMENTS:
  5098.     
  5099.         None
  5100.     
  5101.     
  5102.     RETURN VALUE:
  5103.     
  5104.         None
  5105.     
  5106.     
  5107.     DESCRIPTION:
  5108.     
  5109.           This function updates the real X/Y cursor position  on  the  video
  5110.        screen to reflect the "logical" position  where  the  next  character
  5111.        will be output.
  5112.     
  5113.           The MICRO-C video library  uses  a  BIOS  interrupt  (INT  10)  to
  5114.        position the cursor, which is quite slow, compared to  the  speed  of
  5115.        the library video routines. To prevent this  from  slowing  down  the
  5116.        video output, the cursor is  only  physically  re-positioned  when  a
  5117.        "vgotoxy" or a "vgetc" is executed.
  5118.     
  5119.           This allows the library routines to run at full speed,  and  still
  5120.        put the cursor in the right place when  output  stops  and  an  input
  5121.        request is made.
  5122.     
  5123.           A side effect of this is that the cursor on the  screen  will  not
  5124.        appear to move unless  you  call  "vgotoxy"  or  "vgetc".  This  only
  5125.        affects the physical cursor on the screen, MICRO-C maintains its  own
  5126.        internal cursor location which it uses  to  determine  where  on  the
  5127.        screen the next write will occur.
  5128.     
  5129.           Some applications which run in  real  time  (Such  as  a  terminal
  5130.        emulator) do not call "vgetc", but use "vtstc" to poll  the  keyboard
  5131.        on a regular basis. In this case, the "vupdatexy" routine  should  be
  5132.        called any time that the visual position of the cursor is important.
  5133.     
  5134.           "VOPEN" MUST be called prior to using this function.
  5135.     
  5136.     
  5137.     EXAMPLES:
  5138.     
  5139.         vupdatexy();        /* position the cursor *
  5140.         c = vtstc();        /* Test for a character */
  5141.     MICRO-C Library                                                  Page: 4
  5142.  
  5143.  
  5144.     
  5145.                      +------------------------------------+
  5146.                      |                                    |
  5147.                      |  ********************************  |
  5148.                      |  * The IBM-PC WINDOWING library *  |
  5149.                      |  ********************************  |
  5150.                      |                                    |
  5151.                      +------------------------------------+
  5152.     
  5153.     
  5154.     
  5155.     
  5156.     
  5157.     
  5158.     
  5159.     
  5160.     
  5161.     
  5162.        1.3 IBM-PC WINDOWING Library
  5163.     
  5164.              The MICRO-C WINDOWING LIBRARY is a set of powerful, very  fast,
  5165.           compact, text based windowing functions for use with  the  MICRO-C
  5166.           compiler, on the IBM Personal Computer. Features  of  the  library
  5167.           include multiple open windows,  overlaid  windows  with  automatic
  5168.           save/restore  of  screen  underneath,  scrolling  within  windows,
  5169.           optional window borders, menu and form entry functions, and more.
  5170.     
  5171.              The library is organized into two parts, the first is a set  of
  5172.           assembly language routines which provides the  basic  "low  level"
  5173.           functions to open/close windows, and to output data in  them.  The
  5174.           second part of the library provides a set of 'C'  functions  which
  5175.           provide "high level"  functions  such  as  menu  and  form  entry,
  5176.           formatted printing, etc.
  5177.     MICRO-C Library                                                  Page: 5
  5178.  
  5179.  
  5180.           1.3.1 Window Control Block
  5181.     
  5182.                 Whenever a new window is opened, the windowing library  sets
  5183.              up a WINDOW CONTROL  BLOCK  (WCB)  which  contains  information
  5184.              needed to access and control the window. The format of the  WCB
  5185.              is:
  5186.     
  5187.         Offset: 0   - Current video attribute *
  5188.                 1   - Window flags (High 8 bits of w_open attrs) **
  5189.                 2   - Absolute 'X' position of top left corner of
  5190.                       active region. ***
  5191.                 3   - Absolute 'Y' position of top left corner of
  5192.                       active region. ***
  5193.                 4   - Width in characters of active region ***
  5194.                 5   - Height in characters of active region ***
  5195.                 6   - Current 'X' cursor coordinate
  5196.                 7   - Current 'Y' cursor coordinate
  5197.                 8,9 - Pointer to previous window buffer
  5198.                 10  - Previous cursor ENDING line
  5199.                 11  - Previous cursor STARTING line
  5200.                 12  - Previous cursor absolute 'X' position ****
  5201.                 13  - Previous cursor absolute 'Y' position ****
  5202.                 14..- Save area for SAVE/RESTORE function
  5203.     
  5204.         *       You may dynamically alter the video attribute of data
  5205.                 written to the window by writing to this byte.
  5206.     
  5207.         **      You may dynamically alter the properties of the window by
  5208.                 setting or clearing the flag bits with these exceptions:
  5209.                 -DO NOT enable SAVE/RESTORE unless opened with it
  5210.                 (It is Ok to disable SAVE/RESTORE).
  5211.                 -DO NOT change the state of the BORDER bits.
  5212.     
  5213.         ***     For windows opened with a BORDER, this reflects the size
  5214.                 of the active region (not including the border). Otherwise,
  5215.                 this is the size of the entire window.
  5216.     
  5217.         ****    For full screen window which does not SAVE/RESTORE, you can
  5218.                 set these values to zero to home cursor on exit.
  5219.     MICRO-C Library                                                  Page: 6
  5220.  
  5221.  
  5222.           1.3.2 External Variables
  5223.     
  5224.                 In addition to  the  functions  decribed  on  the  following
  5225.              pages, the windowing library provides  the  following  external
  5226.              variables which may be accessed from within your 'C' program:
  5227.     
  5228.              1.3.2.1 W_BASE
  5229.     
  5230.                                extern int W_BASE;
  5231.     
  5232.                    This variable contains the  base  address  of  the  video
  5233.                 screen, which may be used to determine the type  of  display
  5234.                 present:
  5235.     
  5236.                         B000 = Monochrome
  5237.                         B800 = Color
  5238.     
  5239.     
  5240.              1.3.2.2 W_OPEN
  5241.     
  5242.                               extern char *W_OPEN;
  5243.     
  5244.                    This variable contains a  pointer  to  the  WCB  for  the
  5245.                 "active" window, and controls which window is manipulated by
  5246.                 certain library functions.  This  automatically  set  up  by
  5247.                 "wopen" to point to the  last  window  opened,  but  may  be
  5248.                 changed at any time with:
  5249.     
  5250.                                 W_OPEN = window;
  5251.     
  5252.                    NOTE, when the active window is closed, W_OPEN  is  reset
  5253.                 to point to the window which was active at the time that  it
  5254.                 (the active window) was opened. If  windows  are  closed  in
  5255.                 other than the reverse order  of  which  they  were  opened,
  5256.                 W_OPEN may be left pointing to a window  which  has  already
  5257.                 been closed. If this happens, YOU MUST NOT USE THE  "ACTIVE"
  5258.                 WINDOW FUNCTIONS WITHOUT RESETTING W_OPEN  TO  POINT  TO  AN
  5259.                 OPEN WINDOW. It is your (the programmer's) responsibility to
  5260.                 insure that you know what window will  be  accessed  through
  5261.                 W_OPEN at all times throughout your program.
  5262.     
  5263.           1.3.3 Window Library Functions
  5264.     
  5265.                 The following pages contain a description of  each  function
  5266.              available in the IBM-PC windowing library.
  5267.     WCLEOL                                                           WCLEOL
  5268.     W_CLEOL                                                         W_CLEOL
  5269.     
  5270.     
  5271.     
  5272.     PROTOTYPE:
  5273.     
  5274.         wcleol()
  5275.         w_cleol(char *window)
  5276.     
  5277.     
  5278.     ARGUMENTS:
  5279.     
  5280.         window  - Pointer to WCB for an open window
  5281.     
  5282.     
  5283.     RETURN VALUE:
  5284.     
  5285.         None
  5286.     
  5287.     
  5288.     DESCRIPTION:
  5289.     
  5290.           The "wcleol" function clears the active window  from  the  current
  5291.        cursor position to the end of a line.
  5292.     
  5293.           The "w_cleol" function  clears  the  specified  window  fromt  the
  5294.        current position to the end of the line.
  5295.     
  5296.     
  5297.     EXAMPLES:
  5298.     
  5299.         wputs("Input> ");       /* Display a prompt */
  5300.         wcleol();               /* Clear remainder of input line */
  5301.     WCLEOW                                                           WCLEOW
  5302.     W_CLEOW                                                         W_CLEOW
  5303.     
  5304.     
  5305.     
  5306.     PROTOTYPE:
  5307.     
  5308.         wcleow()
  5309.         w_cleow(char *window)
  5310.     
  5311.     
  5312.     ARGUMENTS:
  5313.     
  5314.         window  - Pointer to WCB for an open window
  5315.     
  5316.     
  5317.     RETURN VALUE:
  5318.     
  5319.         None
  5320.     
  5321.     
  5322.     DESCRIPTION:
  5323.     
  5324.           The "wcleow" function clears the active window  from  the  current
  5325.        position to the end of the window.
  5326.     
  5327.           The "w_cleow"  function  clears  the  specified  window  from  the
  5328.        current position to the end of the window.
  5329.     
  5330.     
  5331.     EXAMPLES:
  5332.     
  5333.         wgotoxy(0, 10);         /* position at line 11 */
  5334.         wcleos();               /* Clear lower part of screen */
  5335.     WCLOSE                                                           WCLOSE
  5336.     W_CLOSE                                                         W_CLOSE
  5337.     
  5338.     
  5339.     
  5340.     PROTOTYPE:
  5341.     
  5342.         wclose()
  5343.         w_close(char *window)
  5344.     
  5345.     
  5346.     ARGUMENTS:
  5347.     
  5348.         window  - Pointer to WCB for an open window
  5349.     
  5350.     RETURN VALUE:
  5351.     
  5352.         None
  5353.     
  5354.     
  5355.     DESCRIPTION:
  5356.     
  5357.           The "wclose" function closes the "active" window, and de-activates
  5358.        it.
  5359.     
  5360.           The  "w_close"  function  closes   the   specified   window,   and
  5361.        de-activates it.
  5362.     
  5363.           If the window being closed is the "active"  window,  the  "active"
  5364.        window will revert to the window which was "active" at the time  that
  5365.        the window being closed was opened.
  5366.     
  5367.     
  5368.     EXAMPLES:
  5369.     
  5370.         wclose();       /* Close active window */
  5371.         w_close(title); /* Close the title window */
  5372.     WCLWIN                                                           WCLWIN
  5373.     W_CLWIN                                                         W_CLWIN
  5374.     
  5375.     
  5376.     
  5377.     PROTOTYPE:
  5378.     
  5379.         wclwin()
  5380.         w_clwin(char *window)
  5381.     
  5382.     
  5383.     ARGUMENTS:
  5384.     
  5385.         window  - Pointer to WCB for an open window
  5386.     
  5387.     
  5388.     RETURN VALUE:
  5389.     
  5390.         None
  5391.     
  5392.     
  5393.     DESCRIPTION:
  5394.     
  5395.           The "wclwin" function clears the entire active window  and  resets
  5396.        the cursor position to the top left hand corner.
  5397.     
  5398.           The "w_clwin" function clears the  entire  specified  window,  and
  5399.        resets the cursor position to the top left hand corner.
  5400.     
  5401.     
  5402.     EXAMPLES:
  5403.     
  5404.         if(c = 0x1b) {          /* Escape command */
  5405.             wclwin();           /* Clear the screen */
  5406.             wputs("Exiting back to main menu");
  5407.             return; }
  5408.     WCURSOR_BLOCK                                             WCURSOR_BLOCK
  5409.     
  5410.     
  5411.     
  5412.     PROTOTYPE:
  5413.     
  5414.         wcursor_block()
  5415.     
  5416.     
  5417.     ARGUMENTS:
  5418.     
  5419.         None
  5420.     
  5421.     
  5422.     RETURN VALUE:
  5423.     
  5424.         None
  5425.     
  5426.     
  5427.     DESCRIPTION:
  5428.     
  5429.           This function enables (turns on) display of the cursor on the  IBM
  5430.        PC video display. The cursor is shown as  flashing  block,  occupying
  5431.        the entire character window.
  5432.     
  5433.     
  5434.     EXAMPLES:
  5435.     
  5436.         if(insert)              /* Test insert mode flag */
  5437.             wcursor_block();    /* Indicate inserting with block cursor */
  5438.         else
  5439.             wcursor_line();     /* Indicate overwrite with line cursor */
  5440.     WCURSOR_LINE                                               WCURSOR_LINE
  5441.     
  5442.     
  5443.     
  5444.     PROTOTYPE:
  5445.     
  5446.         wcursor_line()
  5447.     
  5448.     
  5449.     ARGUMENTS:
  5450.     
  5451.         None
  5452.     
  5453.     
  5454.     RETURN VALUE:
  5455.     
  5456.         None
  5457.     
  5458.     
  5459.     DESCRIPTION:
  5460.     
  5461.           This function enables (turns on) display of the cursor on the  IBM
  5462.        PC video display. The cursor is shown as a single flashing  line,  at
  5463.        the bottom of the character window.
  5464.     
  5465.     
  5466.     EXAMPLES:
  5467.     
  5468.         wcursor_line();     /* Re-enable the cursor */
  5469.         exit(0);            /* And terminate */
  5470.     WCURSOR_OFF                                                 WCURSOR_OFF
  5471.     
  5472.     
  5473.     
  5474.     PROTOTYPE:
  5475.     
  5476.         wcursor_off()
  5477.     
  5478.     
  5479.     ARGUMENTS:
  5480.     
  5481.         None
  5482.     
  5483.     
  5484.     RETURN VALUE:
  5485.     
  5486.         None
  5487.     
  5488.     
  5489.     DESCRIPTION:
  5490.     
  5491.           This function inhibits (turns off) display of the  cursor  on  the
  5492.        IBM PC video display. This affects the cursor  display  only,  screen
  5493.        output will continue to be displayed at the correct cursor position.
  5494.     
  5495.     
  5496.     EXAMPLES:
  5497.     
  5498.         wclscr();           /* Clear screen */
  5499.         wcursor_off();      /* Inhibit cursor */
  5500.         wmenu(10, 10, 0x6007, main_menu, &index); /* Present main menu */
  5501.     WFORM                                                             WFORM
  5502.     
  5503.     
  5504.     
  5505.     PROTOTYPE:
  5506.     
  5507.         register wform(int x, int y, int attrs, char *prompts[],
  5508.                        char *strings,  ...)
  5509.     
  5510.     
  5511.     ARGUMENTS:
  5512.     
  5513.         x       - Absolute COLUMN of upper left corner of form window
  5514.         y       - Absolute ROW    of upper left corner of form window
  5515.         attrs   - Attributes for form window (See WOPEN)
  5516.         prompts - Prompt string for form entries
  5517.         strings - Destination string to receive form data
  5518.         ...     - Additional arguments may be required
  5519.     
  5520.     
  5521.     RETURN VALUE:
  5522.     
  5523.         None
  5524.     
  5525.     
  5526.     DESCRIPTION:
  5527.     
  5528.           The "wform" function opens  a  window,  which  contains  a  "form"
  5529.        consisting of prompts and data areas. Each data area is shown  beside
  5530.        its corresponding prompt, and may be edited using the keys  supported
  5531.        by WGETS. the UP and DOWN ARROW keys may be used to move the  editing
  5532.        cursor between the various fields in the input form.*
  5533.     
  5534.           The "attrs" argument contains the open attributes (see WOPEN)  for
  5535.        the menu window, and may  be  used  to  control  the  color,  border,
  5536.        clearing, etc.
  5537.     
  5538.           The "prompts" argument is an array of pointers to  strings,  which
  5539.        define the prompts and input  fields  in  the  form.  The  first  two
  5540.        characters of each string define the 'X' and 'Y'  coordinates  within
  5541.        the window of the prompt string. The  third  character  contains  the
  5542.        length of the destination string, and the  remainder  of  the  string
  5543.        contains the text prompt. The destination string is positioned in the
  5544.        window directly following the prompt string.  This  list  of  prompts
  5545.        must end with a NULL (0) element.
  5546.     
  5547.           The first (0) element of "prompts" does not actually point  to  an
  5548.        input definition, but contains the X and Y sizes for the window to be
  5549.        opened (High byte = X, Low byte = Y).
  5550.     
  5551.           Following the "prompts" argument, there must  be  one  destination
  5552.        "string" argument for each prompt defined. The strings must  be  long
  5553.        enough to contain the number of characters  specified  in  the  third
  5554.        byte of the coresponding "prompt" string.
  5555.           Only the lower seven bits of the field length are used  (length  =
  5556.        1-127), the high bit indicates that the field is to  contain  numbers
  5557.        only. In this case, the corresponding argument is NOT a pointer to  a
  5558.        string, but must be a pointer to an "int" variable.
  5559.     
  5560.           The form is exited by pressing the ESCAPE key.
  5561.     
  5562.     
  5563.     
  5564.     EXAMPLES:
  5565.     
  5566.         /* Sample input form */
  5567.             char *form[] = {
  5568.                 50<<8|6,        /* Place in 50 by 6 window */
  5569.                 "\x01\x00\x20Software  :",
  5570.                 "\x01\x01\x20Author    :",
  5571.                 "\x01\x02\x20Directory :",
  5572.                 "\x01\x03\x20Filename  :",
  5573.                 0 };
  5574.     
  5575.         /* Data areas for input form */
  5576.             char software[0x21] = "MICRO-C",
  5577.                 author[0x21]    = "Dave Dunfield",
  5578.                 direct[0x21]    = "C:\\MC",
  5579.                 filename[0x21]  = "MC*.*";
  5580.     
  5581.         /* Simple main program to display the form */
  5582.         main()
  5583.         {
  5584.             wform(15, 9, 0xE007, form, software, author, direct, filename);
  5585.         }
  5586.     WGETC                                                             WGETC
  5587.     W_GETC                                                           W_GETC
  5588.     
  5589.     
  5590.     
  5591.     PROTOTYPE:
  5592.     
  5593.         int wgetc()
  5594.         int w_getc(char *window)
  5595.     
  5596.     
  5597.     ARGUMENTS:
  5598.     
  5599.         window  - Pointer to WCB for an open window
  5600.     
  5601.     
  5602.     RETURN VALUE:
  5603.     
  5604.         0-127   - ASCII value of key pressed
  5605.         < 0     - Special function key as defined in "video.h"
  5606.     
  5607.     
  5608.     DESCRIPTION:
  5609.     
  5610.           The "wgetc" function waits until a key is pressed  on  the  system
  5611.        console, and returns its value. The cursor is updated to be placed at
  5612.        the current cursor position in the active window.
  5613.     
  5614.           The "w_getc" function waits until a key is pressed on  the  system
  5615.        console, and returns its value. The cursor is updated to be placed at
  5616.        the current cursor position in the specified window.
  5617.     
  5618.           Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
  5619.        keypress will be reported, even if the WGETC or  W_GETC  function  is
  5620.        called after a key is pressed and released.
  5621.     
  5622.     
  5623.     EXAMPLES:
  5624.     
  5625.         switch(wgetc()) {       /* Handle input keys
  5626.                 . . .
  5627.         }
  5628.     WGETS                                                             WGETS
  5629.     
  5630.     
  5631.     
  5632.     PROTOTYPE:
  5633.     
  5634.         int wgets(int x, int y, char *string, int length)
  5635.     
  5636.     
  5637.     ARGUMENTS:
  5638.     
  5639.         x       - COLUMN position for input
  5640.         y       - ROW    position for input
  5641.         string  - Destination string
  5642.         length  - Length of string (High bit set = Numbers only)
  5643.     
  5644.     
  5645.     RETURN VALUE:
  5646.     
  5647.         Character causing exit
  5648.     
  5649.     
  5650.     DESCRIPTION:
  5651.     
  5652.           The "wgets" function positions the cursor at the specified X and Y
  5653.        coordinates, and displays the contents of "string"  (in  a  field  of
  5654.        "length" characters), and waits for input, which may be used to  edit
  5655.        the string.
  5656.     
  5657.           Any normal ASCII characters which are input will be  entered  into
  5658.        the string, The following function keys are recognized:
  5659.     
  5660.             LEFT ARROW          - Position cursor one space to the left
  5661.             RIGHT ARROW         - Position cursor one space to the right
  5662.             BACKSPACE           - Backup cursor & delete previous character
  5663.             DELETE              - Delete character under cursor
  5664.             INSERT              - Toggle between INSERT/OVERWRITE
  5665.             HOME                - Position cursor at start of string
  5666.             END                 - Position cursor at end of scring
  5667.             PAGE UP             - Clear entire field
  5668.             PAGE DOWN           - Clear from cursor to end of field
  5669.     
  5670.           Any other special function keys will cause "wgets"  to  terminate,
  5671.        and return the value of the offending key. (See  "window.h"  for  key
  5672.        definitions).
  5673.     
  5674.           When INSERT mode is enabled, all entered  text  will  be  inserted
  5675.        into the string, with the remainder of the  string  shifting  to  the
  5676.        right. This mode is indicated by a flashing BLOCK cursor.
  5677.     
  5678.           When OVERWRITE mode is enabled, all entered  text  will  overwrite
  5679.        the existing string. This  mode  is  indicated  by  a  flashing  LINE
  5680.        cursor.
  5681.     
  5682.     
  5683.     EXAMPLES:
  5684.     
  5685.         wgets(2, 5, name, 25);
  5686.     WGOTOXY                                                         WGOTOXY
  5687.     W_GOTOXY                                                       W_GOTOXY
  5688.     
  5689.     
  5690.     
  5691.     PROTOTYPE:
  5692.     
  5693.         wgotoxy(int x, int y)
  5694.         w_gotoxy(int x, int y, char *window)
  5695.     
  5696.     
  5697.     ARGUMENTS:
  5698.     
  5699.         x       - New COLUMN
  5700.         y       - New ROW
  5701.         window  - Pointer to WCB for an open window
  5702.     
  5703.     
  5704.     RETURN VALUE:
  5705.     
  5706.         None
  5707.     
  5708.     
  5709.     DESCRIPTION:
  5710.     
  5711.           The "wgotoxy" function positions  the  cursor  within  the  active
  5712.        window. Any further display output to that window will occur  at  the
  5713.        new ROW and COLUMN positions.
  5714.     
  5715.           The "w_gotoxy" function positions the cursor within the  specified
  5716.        window. Any further display output to that window will occur  at  the
  5717.        new ROW and COLUMN positions.
  5718.     
  5719.     
  5720.     EXAMPLES:
  5721.     
  5722.         for(i=0; i<10; ++i) {   /* Draw a diagonal line of 'X's */
  5723.             wgotoxy(i, i);
  5724.             wputc('X'); }
  5725.     WMENU                                                             WMENU
  5726.     
  5727.     
  5728.     
  5729.     PROTOTYPE:
  5730.     
  5731.         wmenu(int x, int y, int attrs, char *names[], int &index)
  5732.     
  5733.     
  5734.     ARGUMENTS:
  5735.     
  5736.         x       - Absolute COLUMN of top left corner of menu window
  5737.         y       - Absolute ROW    of top left corner of menu window
  5738.         attrs   - Attributes for menu window (see WOPEN)
  5739.         names   - Array to menu selection text (last entry = 0)
  5740.         index   - Address of message selection index variable
  5741.     
  5742.     
  5743.     RETURN VALUE:
  5744.     
  5745.         0   - Selection was made and ENTER pressed.
  5746.         !0  - Menu was aborted via ESCAPE key.
  5747.     
  5748.     
  5749.     DESCRIPTION:
  5750.     
  5751.           The "wmenu" function opens a window  containing  a  list  of  menu
  5752.        items at the specified ROW and COLUMN address. The user may  use  the
  5753.        UP, DOWN, HOME and END keys to select an entry by moving the  INVERSE
  5754.        VIDEO selection cursor. Pressing an alpha-numeric key  will  position
  5755.        the  selection  bar  to  the  first  entry  which  begins  with  that
  5756.        character.
  5757.     
  5758.           When the desired selection is under the cursor, the  selection  is
  5759.        made by pressing the ENTER key.
  5760.     
  5761.           At any time the menu selection may be  canceled  by  pressing  the
  5762.        ESCAPE key.
  5763.     
  5764.           The "attrs" argument contains the open attributes (see WOPEN)  for
  5765.        the menu window, and may  be  used  to  control  the  color,  border,
  5766.        clearing, etc.
  5767.     
  5768.           The "names" argument must be a pointer to an  array  of  character
  5769.        strings which are the selections to display. This array MUST end with
  5770.        a NULL (0) element to indicate the end of the list.
  5771.     
  5772.           The "index" argument is the address of  an  "int"  variable  which
  5773.        contains the position of the selection cursor. It controls where  the
  5774.        selection cursor will appear when the function is first invoked (0  =
  5775.        first entry), and also is assigned  the  position  of  the  selection
  5776.        cursor when the selection is made.
  5777.     
  5778.           Once a selection is made, the first character  of  that  selection
  5779.        will be hilighted in reverse video.
  5780.     
  5781.     
  5782.     
  5783.     
  5784.     EXAMPLES:
  5785.     
  5786.         char *names[] = { "One", "Two", "Three", "Four", "Five", 0 };
  5787.             . . .
  5788.         index = 0;
  5789.         if(wmenu(10, 10, 0xE007, names, &index))
  5790.             return;         /* Aborted, exit to higher level */
  5791.         switch(index) {     /* Handle selection */
  5792.             . . .
  5793.         }
  5794.     WOPEN                                                             WOPEN
  5795.     
  5796.     
  5797.     
  5798.     PROTOTYPE:
  5799.     
  5800.         char *wopen(int x, int y, int width, int height, int attrs)
  5801.     
  5802.     
  5803.     ARGUMENTS:
  5804.     
  5805.         x       - Absolute COLUMN of top left corner of window
  5806.         y       - Absolute ROW    of top left corner of window
  5807.         width   - The width of the window in characters
  5808.         height  - The height of the window in characters
  5809.         attrs   - The window attributes, BIT definitions:
  5810.                     15 - Enable SAVE/RESTORE screen under window
  5811.                 *   14 - Enable SINGLE line BORDER
  5812.                 *   13 - Enable DOUBLE line BORDER
  5813.                     12 - Enable CLEAR on OPEN
  5814.                 **  11 - Enable CLEAR on CLOSE
  5815.                 *** 10 - Disable NEWLINE (LF only)
  5816.                      9 - Enable SCROLLING in window
  5817.                      8 - Enable LINE WRAP in window
  5818.                    7-0 - Video attributes for window
  5819.     
  5820.             *   When BORDER is selected, window will include an enclosing
  5821.                 BOX. In this case, the effective height and width of the
  5822.                 active region (where text data can be written) will be
  5823.                 reduced by 2.
  5824.     
  5825.             **  Has no visual effect when SAVE/RESTORE is enabled.
  5826.     
  5827.             *** If this BIT is set, CTRL-J will behave as LINEFEED only,
  5828.                 and will not return the cursor to the left margin.
  5829.     
  5830.     RETURN VALUE:
  5831.     
  5832.         A pointer to the WCB for the newly opened window
  5833.         0 if the window could not be opened
  5834.     
  5835.     
  5836.     DESCRIPTION:
  5837.     
  5838.           The "wopen" function creates a new window on the PC video  screen.
  5839.        This newly created window is also made the "active" window, which  is
  5840.        automatically accessed by many of the windowing functions.
  5841.     
  5842.           If "wopen" is unable to allocate  enough  memory  for  the  window
  5843.        control block (WCB), it will fail and return a value of zero (0).
  5844.     
  5845.     
  5846.     EXAMPLES:
  5847.     
  5848.         /* Create a title window at top of screen */
  5849.         titlewin = wopen(0, 0, 80, 3, 0x6047);
  5850.     WPRINTF                                                         WPRINTF
  5851.     W_PRINTF                                                       W_PRINTF
  5852.     
  5853.     
  5854.     
  5855.     PROTOTYPE:
  5856.     
  5857.         register wprintf(char *format, arg, ...)
  5858.         register w_printf(char *window, char *format, arg, ...)
  5859.     
  5860.     
  5861.     ARGUMENTS:
  5862.     
  5863.         window  - Pointer to WCB for an open window
  5864.         format  - Pointer to format string
  5865.         arg     - Argument as determined by format string
  5866.         ...     - Additional arguments may be required
  5867.     
  5868.     
  5869.     RETURN VALUE:
  5870.     
  5871.         None
  5872.     
  5873.     
  5874.     DESCRIPTION:
  5875.     
  5876.           The "wprintf" function performs exactly as the  "PRINTF"  function
  5877.        in the standard function library, except that it outputs directly  to
  5878.        the active window using the low level windowing library functions.
  5879.     
  5880.           The "w_printf" function behaves similar to "wprintf", except  that
  5881.        the window to receive the output is specified as the first parameter.
  5882.     
  5883.           These functions should be used  in  preference  to  "PRINTF"  when
  5884.        using the windowing function library since "PRINTF" will not move the
  5885.        windowing librarys cursor, will not use the attributes from the  WCB,
  5886.        and will not respect the boundarys of the window.
  5887.     
  5888.           NOTE: This function uses a variable number of arguments, and  must
  5889.        be declared as "register" (See "window.h").
  5890.     
  5891.     
  5892.     EXAMPLES:
  5893.     
  5894.         wgotoxy(0, 0);
  5895.         wprintf("Window %u", screen);
  5896.     WPUTC                                                             WPUTC
  5897.     W_PUTC                                                           W_PUTC
  5898.     
  5899.     
  5900.     
  5901.     PROTOTYPE:
  5902.     
  5903.         wputc(int c)
  5904.         wputc(int c, char *window)
  5905.     
  5906.     
  5907.     ARGUMENTS:
  5908.     
  5909.         c       - Character to be written to window
  5910.     
  5911.     
  5912.     RETURN VALUE:
  5913.     
  5914.         None
  5915.     
  5916.     
  5917.     DESCRIPTION:
  5918.     
  5919.           This "wputc" function displays a character in the active window at
  5920.        the current cursor position.
  5921.     
  5922.           The "w_putc" functino displays a character in the specified window
  5923.        at the current cursor position.
  5924.     
  5925.           Characters are output in "tty" fashion, with  proper  handling  of
  5926.        control codes such as CARRIAGE-RETURN, LINE-FEED and BELL. The screen
  5927.        will scroll upwards when a NEWLINE is printed on the bottom  line  of
  5928.        the screen, or  when  the  bottom  line  wraps  around  to  the  next
  5929.        (Assuming those options are enabled in the window).
  5930.     
  5931.           Although only the lower 8 bits of a passed value are used, "vputc"
  5932.        will not perform ANY output translations if any of the upper  8  bits
  5933.        are set. This provides a method of displaying  the  video  characters
  5934.        represented by control codes such as NEWLINE, and BACKSPACE.
  5935.     
  5936.           The first byte of the window control block (WCB)  for  the  window
  5937.        contains the attributes which will be used to display the  character.
  5938.        This value is written to the attribute location associated  with  the
  5939.        character on the video display hardware. Its effect is  dependant  on
  5940.        the video  adapter  in  use.  The  "window.h"  header  file  contains
  5941.        definitions of the attribute bits for use  on  "standard"  monochrome
  5942.        and color displays.
  5943.     
  5944.     
  5945.     EXAMPLES:
  5946.     
  5947.         w_putc(0x0A, window1);      /* Line-feed, advance cursor */
  5948.         wputc(0x0A | 0xff00);       /* Display 0x0A character code */
  5949.     WPUTF                                                             WPUTF
  5950.     
  5951.     
  5952.     
  5953.     PROTOTYPE:
  5954.     
  5955.         wputf(char *string, int width)
  5956.     
  5957.     
  5958.     ARGUMENTS:
  5959.     
  5960.         string  - Pointer to character string
  5961.         width   - Width of output field
  5962.     
  5963.     
  5964.     RETURN VALUE:
  5965.     
  5966.         None
  5967.     
  5968.     
  5969.     DESCRIPTION:
  5970.     
  5971.           The "wputf" function outputs a  character  string  to  the  active
  5972.        window screen using the video library functions.
  5973.     
  5974.           The string is left justified in a field of the specified width. If
  5975.        the string is shorter than "width", the field is padded with  blanks.
  5976.        If the string is longer than "width", the output is truncated.
  5977.     
  5978.     
  5979.     EXAMPLES:
  5980.     
  5981.         wputf(message, 10); 
  5982.     WPUTS                                                             WPUTS
  5983.     W_PUTS                                                           W_PUTS
  5984.     
  5985.     
  5986.     
  5987.     PROTOTYPE:
  5988.     
  5989.         wputs(char *string)
  5990.         w_puts(char *string, char *window)
  5991.     
  5992.     
  5993.     ARGUMENTS:
  5994.     
  5995.         string  - Pointer to character string
  5996.         window  - Pointer to WCB for an open window
  5997.     
  5998.     
  5999.     RETURN VALUE:
  6000.     
  6001.         None
  6002.     
  6003.     
  6004.     DESCRIPTION:
  6005.     
  6006.           The "wputs" function outputs a  character  string  to  the  active
  6007.        window.
  6008.     
  6009.           The "w_puts" function output a character string to  the  specified
  6010.        window.
  6011.     
  6012.     
  6013.     EXAMPLES:
  6014.     
  6015.         wputs(message);
  6016.         w_puts(message, window1);
  6017.     WTSTC                                                             WTSTC
  6018.     W_TSTC                                                           W_TSTC
  6019.     
  6020.     
  6021.     
  6022.     PROTOTYPE:
  6023.     
  6024.         int wtstc()
  6025.         int w_tstc(char *window)
  6026.     
  6027.     
  6028.     ARGUMENTS:
  6029.     
  6030.         window  - Pointer to WCB for an open window
  6031.     
  6032.     
  6033.     RETURN VALUE:
  6034.     
  6035.         0       - No key pressed
  6036.         1-127   - ASCII value of key pressed
  6037.         < 0     - Special function key as defined in "video.h"
  6038.     
  6039.     
  6040.     DESCRIPTION:
  6041.     
  6042.           The "wtstc" function  tests  for  a  key  pressed  on  the  system
  6043.        console, and returns its value. If a character is found,  the  cursor
  6044.        is updated in the active window.
  6045.     
  6046.           The "w_tstc" function tests  for  a  key  pressed  on  the  system
  6047.        console, and returns its value. If a character is found,  the  cursor
  6048.        is updated in the specified window.
  6049.     
  6050.           A returned value of zero (0) indicates that no key was found to be
  6051.        pressed.
  6052.     
  6053.           Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
  6054.        keypress will be reported, even if the WTSTC or  W_TSTC  function  is
  6055.        called after a key is pressed and released.
  6056.     
  6057.     
  6058.     EXAMPLES:
  6059.     
  6060.         if(wtstc() == 0x1B) /* exit loop on ESCAPE key */
  6061.             break;
  6062.     WUPDATEXY                                                     WUPDATEXY
  6063.     W_UPDATEXY                                                   W_UPDATEXY
  6064.     
  6065.     
  6066.     
  6067.     PROTOTYPE:
  6068.     
  6069.         wupdatexy()
  6070.         w_updatexy(char *window)
  6071.     
  6072.     
  6073.     ARGUMENTS:
  6074.     
  6075.         window  - Pointer to WCB for an open window
  6076.     
  6077.     
  6078.     RETURN VALUE:
  6079.     
  6080.         None
  6081.     
  6082.     
  6083.     DESCRIPTION:
  6084.     
  6085.           The "wupdatexy" function updates the real X/Y cursor  position  on
  6086.        the video screen to reflect the "logical"  position  where  the  next
  6087.        character will be output in the active window.
  6088.     
  6089.           The "w_updatexy" function updates the real X/Y cursor position  on
  6090.        the video screen to reflect the "logical"  position  where  the  next
  6091.        character will be output in the specified window.
  6092.     
  6093.           The MICRO-C Windowing library uses a BIOS interrupt  (INT  10)  to
  6094.        position the cursor, which is quite slow, compared to  the  speed  of
  6095.        the library video routines. To prevent this  from  slowing  down  the
  6096.        video output, the cursor is  only  physically  re-positioned  when  a
  6097.        "wgotoxy" or a "wgetc" is executed.
  6098.     
  6099.           This allows the library routines to run at full speed,  and  still
  6100.        put the cursor in the right place when  output  stops  and  an  input
  6101.        request is made.
  6102.     
  6103.           A side effect of this is that the cursor on the  screen  will  not
  6104.        appear to move unless  you  call  "wgotoxy"  or  "wgetc".  This  only
  6105.        affects the physical cursor on the screen, MICRO-C maintains its  own
  6106.        internal cursor location which it uses  to  determine  where  on  the
  6107.        screen the next write will occur.
  6108.     
  6109.           Some applications which run in  real  time  (Such  as  a  terminal
  6110.        emulator) do not call "wgetc", but use "wtstc" to poll  the  keyboard
  6111.        on a regular basis. In this case, the "wupdatexy" routine  should  be
  6112.        called any time that the visual position of the cursor is important.
  6113.     
  6114.     
  6115.     EXAMPLES:
  6116.     
  6117.         wupdatexy();        /* position the cursor *
  6118.         c = wtstc();        /* Test for a character */
  6119.  
  6120.  
  6121.  
  6122.                                 MICRO-C Library
  6123.  
  6124.                                TABLE OF CONTENTS
  6125.  
  6126.  
  6127.                                                                          Page
  6128.  
  6129.      1. THE MICRO-C LIBRARIES                                               1
  6130.  
  6131.         1.1 STANDARD Library                                                2
  6132.         1.2 IBM-PC/MS-DOS Library                                           3
  6133.         1.3 IBM-PC WINDOWING Library                                        4
  6134.